@milpa/comal 0.2.6 → 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/relay/flow.mjs

@@ -558,7 +558,7 @@ export class RelayFlow {
       if (got?.proposal?.status && got.proposal.status !== 'pending') { this.ui.notice(t('Plan {id} is already {status}.', { id: proposal_id, status: got.proposal.status })); return 'decided'; }
       // Cómo se comprueba cada tarea: la descripción de los checks del proyecto (project.json del hub).
       const checks = (await this.#projectFile({ root }, project))?.checks || [];
-      const choice = await this.ui.setupChoice({ ...planCard({ got, checks }), signal: card.signal });
+      const choice = await this.ui.setupChoice({ waits: true, ...planCard({ got, checks }), signal: card.signal });
       if (this.#elsewhere(key)) return 'decided';
       const digest = got.proposal.digest, apply = extra => () => this.applyPlan({ project, root, swarm, proposal_id, digest, ...extra });
       const done = result => {
@@ -569,7 +569,7 @@ export class RelayFlow {
       };
       if (choice === 'approve') return await this.#confirm(key, apply({ choice: 'approve' }), done);
       if (choice === 'reject') {
-        const reason = await this.ui.setupInput({ title: t('Reason for the lead'), description: t('The lead is woken up with exactly this text and proposes again.'), signal: card.signal });
+        const reason = await this.ui.setupInput({ waits: true, title: t('Reason for the lead'), description: t('The lead is woken up with exactly this text and proposes again.'), signal: card.signal });
         if (this.#elsewhere(key)) return 'decided';
         if (!reason?.trim()) return 'later';
         return await this.#confirm(key, apply({ choice: 'reject', reason: reason.trim() }), done);
@@ -618,7 +618,7 @@ export class RelayFlow {
     if (this.#elsewhere(key)) return 'decided';
     const card = this.broker.open(key, this.signal);
     try {
-      const choice = await this.ui.setupChoice({ ...criteriaCard({ got, swarm }), signal: card.signal });
+      const choice = await this.ui.setupChoice({ waits: true, ...criteriaCard({ got, swarm }), signal: card.signal });
       if (this.#elsewhere(key)) return 'decided';
       const done = result => {
         if (result.outcome === 'approved') this.ui.notice(t('Success criteria v{version} accepted ({status}): the lead can plan.', { version: got.current.version, status: result.status }));
@@ -630,14 +630,14 @@ export class RelayFlow {
         // open-relay v2.33: con avisos, aceptar se confirma aparte (por omisión, volver).
         const warnings = criteriaWarnings(got.current.items, { checked: got.basis_checked === true });
         if (warnings.size) {
-          const sure = await this.ui.setupChoice({ ...criteriaConfirmCard({ got, swarm, warnings }), signal: card.signal });
+          const sure = await this.ui.setupChoice({ waits: true, ...criteriaConfirmCard({ got, swarm, warnings }), signal: card.signal });
           if (this.#elsewhere(key)) return 'decided';
           if (sure !== 'accept') return 'later';
         }
         return await this.#confirm(key, () => this.applyCriteria({ project, root, swarm, digest, choice: 'accept' }), done);
       }
       if (choice === 'reject') {
-        const reason = await this.ui.setupInput({ title: t('Reason for the reviewer'), description: t('The reviewer is woken up with exactly this text and proposes again.'), signal: card.signal });
+        const reason = await this.ui.setupInput({ waits: true, title: t('Reason for the reviewer'), description: t('The reviewer is woken up with exactly this text and proposes again.'), signal: card.signal });
         if (this.#elsewhere(key)) return 'decided';
         if (!reason?.trim()) return 'later';
         return await this.#confirm(key, () => this.applyCriteria({ project, root, swarm, digest, choice: 'reject', reason: reason.trim() }), done);
@@ -653,7 +653,7 @@ export class RelayFlow {
     const { call, mutate } = this.#calls(project, root);
     const got = await call('criteria.get', { swarm_id: swarm }, this.signal);
     if (got?.status !== 'accepted' || got?.current?.digest !== digest) { this.ui.notice(t('Criteria of {swarm} are already {status}.', { swarm, status: got?.status || '?' })); return 'decided'; }
-    const reason = await this.ui.setupInput({ title: t('Why reopen the criteria'), description: t('The reviewer is woken up with exactly this text and proposes a new version; v{version} stays in force until you accept the new one.', { version: got.current.version }), signal: this.signal });
+    const reason = await this.ui.setupInput({ waits: true, title: t('Why reopen the criteria'), description: t('The reviewer is woken up with exactly this text and proposes a new version; v{version} stays in force until you accept the new one.', { version: got.current.version }), signal: this.signal });
     if (!reason?.trim()) return 'later';
     const result = await reopenCriteria(mutate, { swarm_id: swarm, digest, reason: reason.trim() }, this.signal);
     await this.record({ action: 'criteria.reopen', project, swarm, digest, version: got.current.version, reason: reason.trim(), status: result.status, idempotency_key: result.idempotency_key });
@@ -683,9 +683,9 @@ export class RelayFlow {
     const { call, mutate } = this.#calls(project, root);
     const got = await call('task.get', { task_id: brief?.id }, this.signal), task = got?.task || got;
     if (task?.state !== 'needs_attention' || !task?.review?.pending) { this.ui.notice(t('The review of {task} no longer waits for you.', { task: line(brief?.id || '?', 60) })); return 'decided'; }
-    const choice = await this.ui.setupChoice({ ...escalationCard({ task }), signal: this.signal });
+    const choice = await this.ui.setupChoice({ waits: true, ...escalationCard({ task }), signal: this.signal });
     if (choice === 'retry') {
-      const why = await this.ui.setupInput({ title: t('Why another review'), description: t('Recorded in relayd as your decision (review.retry) with exactly this text; the reviewer gets a new review task.'), signal: this.signal });
+      const why = await this.ui.setupInput({ waits: true, title: t('Why another review'), description: t('Recorded in relayd as your decision (review.retry) with exactly this text; the reviewer gets a new review task.'), signal: this.signal });
       if (!why?.trim()) return 'later';
       const retried = await retryReview(mutate, { task_id: task.id, reason: why.trim() }, this.signal);
       await this.record({ action: 'review.retry', project, swarm, task: task.id, reason: why.trim(), status: retried.status, idempotency_key: retried.idempotency_key });
@@ -693,7 +693,7 @@ export class RelayFlow {
       return 'decided';
     }
     if (choice !== 'override') return 'later';
-    const reason = await this.ui.setupInput({ title: t('Why you accept over the reviewer'), description: t('Recorded in relayd as your decision (review.override) with exactly this text.'), signal: this.signal });
+    const reason = await this.ui.setupInput({ waits: true, title: t('Why you accept over the reviewer'), description: t('Recorded in relayd as your decision (review.override) with exactly this text.'), signal: this.signal });
     if (!reason?.trim()) return 'later';
     const result = await overrideReview(mutate, { task_id: task.id, reason: reason.trim() }, this.signal);
     await this.record({ action: 'review.override', project, swarm, task: task.id, reason: reason.trim(), status: result.status, idempotency_key: result.idempotency_key });
@@ -723,7 +723,7 @@ export class RelayFlow {
     try {
       const { call } = this.#calls(project, root);
       const message = await call('msg.get', { message_id }, card.signal), block = decisionBlock(message);
-      const choice = await this.ui.setupChoice({ ...questionCard({ message, block, task }), signal: card.signal });
+      const choice = await this.ui.setupChoice({ waits: true, ...questionCard({ message, block, task }), signal: card.signal });
       if (this.#elsewhere(key)) return 'decided';
       const done = result => {
         if (result.outcome === 'decided') this.ui.notice(t('Decision recorded as {adr} and sent to {to}.', { adr: result.adr || '?', to: result.to }));
@@ -733,14 +733,14 @@ export class RelayFlow {
       };
       if (choice?.startsWith('option:') && block) {
         const index = Number(choice.slice(7)), option = block.options[index]?.label; if (!option) return 'later';
-        const note = await this.ui.setupInput({ title: t('Note for the ADR (optional)'), description: t('Why you choose «{option}». Enter with nothing skips it; it goes into the ADR decision.', { option }), signal: card.signal });
+        const note = await this.ui.setupInput({ waits: true, title: t('Note for the ADR (optional)'), description: t('Why you choose «{option}». Enter with nothing skips it; it goes into the ADR decision.', { option }), signal: card.signal });
         if (this.#elsewhere(key)) return 'decided';
         if (note === null || note === undefined) return 'later';
         return await this.#confirm(key, () => this.applyQuestion({ project, root, swarm, message_id, mode: 'option', option_index: index, text: note }), done);
       }
       if (choice === 'reply') {
         const to = message?.from?.role ? `role ${line(message.from.role, 60)}` : line(message?.from?.kind || '?', 40);
-        const body = await this.ui.setupInput({ title: t('Your answer'), description: t('Exact text sent to {to} (msg.reply).', { to }), signal: card.signal });
+        const body = await this.ui.setupInput({ waits: true, title: t('Your answer'), description: t('Exact text sent to {to} (msg.reply).', { to }), signal: card.signal });
         if (this.#elsewhere(key)) return 'decided';
         if (!body?.trim()) return 'later';
         return await this.#confirm(key, () => this.applyQuestion({ project, root, swarm, message_id, mode: 'reply', text: body }), done);
@@ -856,7 +856,7 @@ export class RelayFlow {
     const id = line(task?.id || '?', 60), controlDir = path.join(hubRoot || '.', 'projects', project, 'ctl');
     const command = `relay --control-dir ${shellWord(controlDir)} task resume ${shellWord(String(task?.id || '?'))}`;
     const why = String(detail?.state || '').startsWith('blocked') || detail?.state === 'needs_attention' ? blockLabel(detail.state) : null;
-    const choice = await this.ui.setupChoice({ ...blockedCard({ task: detail, reason, check, at: at ?? task?.since, why, retry: { command } }), signal: this.signal });
+    const choice = await this.ui.setupChoice({ waits: true, ...blockedCard({ task: detail, reason, check, at: at ?? task?.since, why, retry: { command } }), signal: this.signal });
     if (choice !== 'retry') return 'later';
     this.ui.notice(t('Retry it yourself in your terminal, exactly: {command}', { command }));
     await this.record({ action: 'blocked.shown', project, swarm, task: task?.id || null, check: check || null, reason: line(reason || '', 200) });
@@ -876,7 +876,7 @@ export class RelayFlow {
     const review = await this.#finalReview({ root: root || this.current?.hub_root, project, tasks });
     await this.state.setSwarm(project, swarm, { finished_at: new Date().toISOString() });
     await this.record({ action: 'swarm.finished', project, swarm, branch, base_commit: base || null, counts, ok, evidence: evidence.length });
-    const choice = await this.ui.setupChoice({ ...finishCard({ swarm, objective: info.objective || view?.objective, branch, counts, diffStat: stat, base: base || '?', ok, evidence, review }), signal: this.signal });
+    const choice = await this.ui.setupChoice({ waits: true, ...finishCard({ swarm, objective: info.objective || view?.objective, branch, counts, diffStat: stat, base: base || '?', ok, evidence, review }), signal: this.signal });
     if (choice === 'diff' && base) {
       const diff = await this.git.diff(repo, base, branch);
       this.ui.commandResult?.('relay', 'diff', (diff.truncated ? t('Diff of {branch} ({count} more lines not shown; git diff {base}..{branch})', { branch, count: diff.truncated, base: base.slice(0, 8) }) + '\n\n' : '') + diff.text);

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

@@ -280,7 +280,7 @@ export class InteractiveController {
     if(state.reason==='authentication' && loginProvider)items.push({id:'login',label:t('Sign in to the selected provider'),description:loginProvider});
     items.push({id:'choose',label:t('Choose another connection'),description:t('Open the provider and workspace profile selector.')});
     const reason=CONNECTION_REASON_HINTS[state.reason];
-    const choice=await this.ui.setupChoice({title:t(state.confirmedUnchanged?'Connection change not applied':'Connection status needs review'),description:t(state.message)+(reason?'\n\n'+t(reason):''),items});
+    const choice=await this.ui.setupChoice({waits:true,title:t(state.confirmedUnchanged?'Connection change not applied':'Connection status needs review'),description:t(state.message)+(reason?'\n\n'+t(reason):''),items});
     if(this.closed)return;
     if(choice==='retry' && this.connections.canRetry(id))await this.submit(`/${action.command} ${action.argument}`);
     else if(choice==='login')await this.submit(`/login ${loginProvider}`);
@@ -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"));