@milpa/comal 0.2.7 → 0.2.8

package/src/plugin-controls.mjs

@@ -1,19 +1,22 @@
-import { open, readFile, rename, rm, mkdir } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
-import path from 'node:path';
-import { readPluginConfig } from './plugin-config.mjs';
+import { readPluginConfig, readPluginConfigRaw as readRaw, writePluginConfigRaw as writeRaw } from './plugin-config.mjs';
 import { parsePluginCommand } from './plugins.mjs';
 import { PluginTrustStore, pluginTrustFile, trustVerdict, configDigest } from './plugin-trust.mjs';
 import { PermissionRules, permissionRulesFile, parseGroup, ruleText } from './permission-rules.mjs';
 import { bundledPlugins, bundledPlugin, pluginOperations, parseAssignments, validateBundledConfig, operationName } from './plugin-catalog.mjs';
 import { t, registerMessages } from './i18n/index.mjs';
+import { readRepairRecords, readActRecords, repairRecordFile, repairChain, markRepairReverted, overlaysDir, actsDir, realLocation } from './plugin-repair.mjs';
+import { readFile, writeFile, rename, rm } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { inspectPluginModule } from './plugin-config.mjs';
+import { defaultStateDir } from './compat.mjs';
+import path from 'node:path';
 
 registerMessages({
   'Use /plugins {usage}.': 'Usa /plugins {usage}.',
   'add ID [key=value…]': 'add ID [clave=valor…]',
   'config ID [key=value…]': 'config ID [clave=valor…]',
   'allow ID observe|all|none|OPERATION…': 'allow ID observe|all|none|OPERACIÓN…',
-  'Use /plugins [list|available|add ID [k=v…]|remove ID|config ID [k=v…]|enable ID|disable ID|reload [ID]|trust|untrust ID|allow ID observe|all|none|OP…|run ID OPERATION {JSON}].': 'Usa /plugins [list|available|add ID [k=v…]|remove ID|config ID [k=v…]|enable ID|disable ID|reload [ID]|trust|untrust ID|allow ID observe|all|none|OP…|run ID OPERACIÓN {JSON}].',
+  'Use /plugins [list|available|add ID [k=v…]|remove ID|config ID [k=v…]|enable ID|disable ID|reload [ID]|trust|untrust ID|allow ID observe|all|none|OP…|run ID OPERATION {JSON}|repairs|acts|revert ID].': 'Usa /plugins [list|available|add ID [k=v…]|remove ID|config ID [k=v…]|enable ID|disable ID|reload [ID]|trust|untrust ID|allow ID observe|all|none|OP…|run ID OPERACIÓN {JSON}|repairs|acts|revert ID].',
   'Use /chrome-workflow [auto|raw].': 'Usa /chrome-workflow [auto|raw].',
   'Plugin {id}: the remembered trust is no longer current ({reasons}); it stays in pending_trust. Review it with /plugins enable {id}.': 'Plugin {id}: la confianza recordada ya no es vigente ({reasons}); queda en pending_trust. Revísalo con /plugins enable {id}.',
   '{id}: trust current · active · {grants}': '{id}: confianza vigente · activo · {grants}',
@@ -76,6 +79,46 @@ registerMessages({
   'Chrome workflow: effective {effective} · saved in the project: {saved}': 'Chrome workflow: efectivo {effective} · guardado en el proyecto: {saved}',
   '(nothing)': '(nada)',
   'Chrome workflow {mode} saved for this project and applied to this session input.': 'Chrome workflow {mode} guardado para este proyecto y aplicado a la entrada de esta sesión.',
+  ' · recorded by the house for a contract repair (/plugins repairs)': ' · registrada por la casa para una reparación por contrato (/plugins repairs)',
+  'Plugin {id}: the installed plugin changed since the repair (fingerprint {before} → {now}); the repaired copy is still the one in use. /plugins revert {id} tries the installed one.': 'Plugin {id}: el plugin instalado cambió desde la reparación (huella {before} → {now}); la copia reparada sigue siendo la que se usa. /plugins revert {id} prueba la instalada.',
+  'Plugin {id}: its contract cannot be stated ({reason}). It loaded and serves as before, but it cannot be repaired by contract until its author fixes that.': 'Plugin {id}: su contrato no se puede enunciar ({reason}). Se cargó y sirve como antes, pero no se puede reparar por contrato hasta que su autor lo corrija.',
+  'Repairs: {dir}': 'Reparaciones: {dir}',
+  'No accepted repairs in this project.': 'No hay reparaciones aceptadas en este proyecto.',
+  'Showing the {shown} most recent of {total}.': 'Se muestran las {shown} más recientes de {total}.',
+  'contract kept': 'contrato cumplido',
+  'signed act': 'acta firmada',
+  'in use': 'en uso',
+  'reverted {at}': 'revertida {at}',
+  'no longer in use': 'ya no en uso',
+  'unchanged since the repair': 'sin cambios desde la reparación',
+  'changed since the repair (fingerprint {before} → {now})': 'cambió desde la reparación (huella {before} → {now})',
+  'missing ({reason})': 'no disponible ({reason})',
+  '    fingerprint {before} → {after} · {below}': '    huella {before} → {after} · {below}',
+  'live': 'viva',
+  'on top of repair {fingerprint}': 'sobre la reparación {fingerprint}',
+  'on top of the original': 'sobre el original',
+  'Plugin {id} has active consumers ({consumers}); disable them before reverting. Nothing was changed.': 'El plugin {id} tiene consumidores activos ({consumers}); desactívalos antes de revertir. No se cambió nada.',
+  'The original module of {id} ({module}) is missing or cannot be read ({reason}). Nothing was changed.': 'El módulo original de {id} ({module}) no está o no se puede leer ({reason}). No se cambió nada.',
+  'The revert of {id} failed while reloading ({reason}). {file} and the repair\'s trust were put back; the repair stays.': 'La reversión de {id} falló al recargar ({reason}). Se restauraron {file} y la confianza de la reparación; la reparación se queda.',
+  'The revert of {id} failed while reloading ({reason}). {file} was edited meanwhile and was left as it is; check it with /plugins.': 'La reversión de {id} falló al recargar ({reason}). {file} se editó mientras tanto y se dejó como está; revísalo con /plugins.',
+  '    cases run: {cases}': '    casos ejecutados: {cases}',
+  '    patch: {patch}': '    parche: {patch}',
+  '    installed original: {state} · {module}': '    original instalado: {state} · {module}',
+  'Signed acts: {dir}': 'Actas firmadas: {dir}',
+  'No signed acts in this project.': 'No hay actas firmadas en este proyecto.',
+  '{plugin} · {at} · reason: {reason}': '{plugin} · {at} · motivo: {reason}',
+  '(none given)': '(sin motivo)',
+  '    surface changed: {items}': '    superficie cambiada: {items}',
+  '    code the house cannot follow: {items}': '    código que la casa no puede seguir: {items}',
+  '    cases added: {added} · removed: {removed} · changed: {changed}': '    casos agregados: {added} · quitados: {removed} · cambiados: {changed}',
+  '    used by the repair accepted at {at} (fingerprint {fingerprint})': '    usada por la reparación aceptada el {at} (huella {fingerprint})',
+  '    no repair stands on it': '    ninguna reparación se apoya en ella',
+  'A repair of {id} is in progress in this session; let it be accepted or discarded first.': 'Hay una reparación de {id} en curso en esta sesión; espera a que se acepte o se descarte.',
+  '{id} has no repair to revert (no repaired_from in {file}).': '{id} no tiene una reparación que revertir (no hay repaired_from en {file}).',
+  'Reverted {id}: {file} points at the original {module} again; the trust the house recorded for the repair was removed.': 'Revertido {id}: {file} vuelve a apuntar al original {module}; se retiró la confianza que la casa registró para la reparación.',
+  'Reverted {id}: {file} points at the original {module} again.': 'Revertido {id}: {file} vuelve a apuntar al original {module}.',
+  'The repaired copy no longer serves: {id} waits for your trust in the installed code (/plugins enable {id}).': 'La copia reparada ya no sirve: {id} espera tu confianza en el código instalado (/plugins enable {id}).',
+  '{id} is not active in this session; /plugins enable {id} loads the installed code.': '{id} no está activo en esta sesión; /plugins enable {id} carga el código instalado.',
 });
 
 // Controles humanos de plugins desde la sesión: catálogo, alta/baja, confianza
@@ -97,9 +140,12 @@ export function parsePluginControl(text = '') {
   if (action === 'config') return { name: 'PluginConfigure', input: { id: needId('config ID [key=value…]'), set: settings() } };
   if (action === 'trust' && !rest.length) return { name: 'PluginTrustList', input: {} };
   if (action === 'untrust') { needId('untrust ID'); if (rest.length > 1) throw new Error(t('Use /plugins {usage}.', { usage: 'untrust ID' })); return { name: 'PluginUntrust', input: { id } }; }
+  if (action === 'repairs' && !rest.length) return { name: 'PluginRepairs', input: {} };
+  if (action === 'acts' && !rest.length) return { name: 'PluginActs', input: {} };
+  if (action === 'revert') { needId('revert ID'); if (rest.length > 1) throw new Error(t('Use /plugins {usage}.', { usage: 'revert ID' })); return { name: 'PluginRevert', input: { id } }; }
   if (action === 'allow') { needId('allow ID observe|all|none|OPERATION…'); if (rest.length < 2) throw new Error(t('Use /plugins {usage}.', { usage: t('allow ID observe|all|none|OPERATION…') })); return { name: 'PluginAllow', input: { id, operations: rest.slice(1) } }; }
   try { return parsePluginCommand(text); }
-  catch { throw new Error(t('Use /plugins [list|available|add ID [k=v…]|remove ID|config ID [k=v…]|enable ID|disable ID|reload [ID]|trust|untrust ID|allow ID observe|all|none|OP…|run ID OPERATION {JSON}].')); }
+  catch { throw new Error(t('Use /plugins [list|available|add ID [k=v…]|remove ID|config ID [k=v…]|enable ID|disable ID|reload [ID]|trust|untrust ID|allow ID observe|all|none|OP…|run ID OPERATION {JSON}|repairs|acts|revert ID].')); }
 }
 
 export function parseChromeWorkflow(text = '') {
@@ -108,33 +154,21 @@ export function parseChromeWorkflow(text = '') {
   return { name: 'ChromeWorkflow', input: mode ? { mode } : {} };
 }
 
-async function readRaw(file) {
-  const source = await readPluginConfig(file, { missing: true }); // valida y acota
-  if (!source.hash) return { plugins: [] };
-  return JSON.parse(await readFile(file, 'utf8'));
-}
-
-// Escribe en un temporal del mismo directorio, lo valida con el lector real y lo publica con rename.
-async function writeRaw(file, value) {
-  await mkdir(path.dirname(file), { recursive: true });
-  const temporary = path.join(path.dirname(file), `.plugins-${randomUUID()}.json`);
-  try {
-    const handle = await open(temporary, 'wx', 0o644);
-    try { await handle.writeFile(JSON.stringify(value, null, 2) + '\n'); await handle.sync(); } finally { await handle.close(); }
-    const checked = await readPluginConfig(temporary);
-    await rename(temporary, file);
-    return checked;
-  } catch (error) { await rm(temporary, { force: true }); throw error; }
-}
-
 export class PluginControls {
-  constructor({ runtime, policy, cwd, trustStore, rules, confirm, trustByFlag = false, onWorkflow = async () => {}, currentWorkflow = () => null, notice = () => {} }) {
-    Object.assign(this, { runtime, policy, cwd, confirm, trustByFlag, onWorkflow, currentWorkflow, notice });
+  /**
+   * stateDir: where the house keeps overlays and the records of repairs and acts (--state-dir, or the
+   * project's default). journal(row): appends a row to the session journal (plugin_repair_reverted).
+   * repair (set by the host): the PluginRepair of this process, asked whether a repair is in progress.
+   */
+  constructor({ runtime, policy, cwd, trustStore, rules, confirm, trustByFlag = false, onWorkflow = async () => {}, currentWorkflow = () => null, notice = () => {}, stateDir, journal = async () => null }) {
+    Object.assign(this, { runtime, policy, cwd, confirm, trustByFlag, onWorkflow, currentWorkflow, notice, journal });
+    // By its real path, resolved once: overlays are recorded by real path, and a symlinked .comal or --state-dir must compare equal.
+    this.stateDir = realLocation(path.resolve(cwd ?? process.cwd(), stateDir ?? defaultStateDir(cwd ?? process.cwd())));
     this.store = trustStore || new PluginTrustStore({ file: pluginTrustFile(), workspace: cwd });
     this.rules = rules || new PermissionRules({ file: permissionRulesFile(), workspace: cwd });
     // Grupos declarados por plugins incluidos; plugin:ID:all lo resuelve el almacén.
     this.rules.groups = (id, group) => { const split = pluginOperations(id); return group === 'observe' ? split?.observations : group === 'actions' ? split?.actions : undefined; };
-    this.rules.gate = name => this.codeTrusted(name);
+    this.rules.gate = (name, context) => this.codeTrusted(name, context);
     policy.rules = this.rules;
   }
   get project() { return this.runtime.file; }
@@ -152,19 +186,56 @@ export class PluginControls {
     for (const warning of [this.store.warning, this.rules.warning]) if (warning) this.notice(warning);
     const status = await this.runtime.initialize({ trust, trusted: trust ? undefined : this.trusted, signal });
     for (const plugin of status.plugins) if (plugin.trust?.status === 'stale') this.notice(t('Plugin {id}: the remembered trust is no longer current ({reasons}); it stays in pending_trust. Review it with /plugins enable {id}.', { id: plugin.id, reasons: plugin.trust.reasons.join(', ') }));
+    // Loading stays compatible: a plugin whose contract cannot be stated still serves. Said once per start.
+    this.#contractNotices();
+    await this.#repairNotices().catch(() => {});
     return status;
   }
+  // One notice per repaired plugin per start when the human's original (repaired_from) is no longer the code
+  // the FIRST repair of the chain started from (its `fingerprint_before`): an update was installed.
+  async #repairNotices() {
+    const raw = await readRaw(this.project), told = new Set();
+    for (const entry of raw.plugins) {
+      if (typeof entry?.repaired_from !== 'string' || typeof entry.module !== 'string' || told.has(entry.id)) continue;
+      const first = await this.#firstRepair(entry.id, entry.module, entry.repaired_from);
+      if (!first) continue;
+      const original = await this.#original(entry.repaired_from, first.fingerprint_before);
+      if (original.changed) { told.add(entry.id); this.notice(t('Plugin {id}: the installed plugin changed since the repair (fingerprint {before} → {now}); the repaired copy is still the one in use. /plugins revert {id} tries the installed one.', { id: entry.id, before: first.fingerprint_before.slice(0, 12), now: original.fingerprint.slice(0, 12) })); }
+    }
+  }
+  // The first repair under a live overlay, when the chain is whole and it started from this original.
+  async #firstRepair(id, module, original) {
+    const { records, complete } = await repairChain(this.stateDir, id, this.#resolve(module));
+    const first = records.at(-1), before = first?.before_module ?? first?.repaired_from;
+    return complete && typeof first.fingerprint_before === 'string' && typeof before === 'string' && path.resolve(before) === this.#resolve(original) ? first : null;
+  }
+  #resolve(module) { return realLocation(path.resolve(path.dirname(this.project), module)); }
+  // The current state of the code a repair started from, against the fingerprint recorded then.
+  async #original(module, before) {
+    try { const code = await inspectPluginModule(this.#resolve(module)); return { fingerprint: code.code_fingerprint, changed: code.code_fingerprint !== before, text: code.code_fingerprint === before ? t('unchanged since the repair') : t('changed since the repair (fingerprint {before} → {now})', { before: before.slice(0, 12), now: code.code_fingerprint.slice(0, 12) }) }; }
+    catch (error) { return { fingerprint: null, changed: false, missing: true, text: t('missing ({reason})', { reason: error.code || error.message }) }; }
+  }
   /**
    * Veto de reglas allow para operaciones de plugins locales: sólo valen mientras la
    * generación viva tenga el mismo módulo, huella y config que el registro de confianza.
    * Se evalúa en cada decisión, así que una recarga con otro código nunca hereda permisos.
    */
-  codeTrusted(name) {
+  codeTrusted(name, context) {
     const match = /^plugin__([a-z][a-z0-9-]*)__/.exec(name); if (!match) return true;
     const plugin = this.#live(match[1]);
     if (!plugin || plugin.builtin) return Boolean(plugin);
     const saved = this.store.find(this.project, plugin.id), entry = this.runtime.desired?.entries.find(item => item.id === plugin.id);
-    return Boolean(plugin.state === 'active' && plugin.code_fingerprint && saved && entry && saved.module === plugin.module && saved.code_fingerprint === plugin.code_fingerprint && saved.config_sha256 === configDigest(entry.config));
+    if (plugin.state === 'active' && plugin.code_fingerprint && saved && entry && saved.module === plugin.module && saved.code_fingerprint === plugin.code_fingerprint && saved.config_sha256 === configDigest(entry.config)) return true;
+    // A contract repair under verification (plugin-repair.mjs, Accept step 6): the human's saved rules name
+    // this plugin's operations, and the house has already established that the published contract equals
+    // the live one (or the human signed the act for it), so they are the same promises. The rules that
+    // applied to the previous generation keep applying, only to the house's own case runs (the invocation
+    // nested directly under that Accept), only for the overlay's exact code and the same configuration,
+    // and only while the trust record is still the human's for the previous code. Nothing is written.
+    // deny and ask are decided before this gate and are never affected.
+    const standing = this.repairStanding?.(plugin.id, context?.invocation);
+    return Boolean(standing && plugin.state === 'active' && entry && standing.module === plugin.module && standing.code_fingerprint === plugin.code_fingerprint
+      && standing.config_sha256 === configDigest(entry.config) && saved && saved.module === standing.previous.module && saved.code_fingerprint === standing.previous.code_fingerprint && saved.config_sha256 === standing.config_sha256);
   }
   // Reglas allow de este proyecto que apuntan al plugin (nombres exactos o grupos plugin:ID:*).
   #pluginAllow(id) { return rule => rule.list === 'allow' && rule.scope === this.rules.scope && (rule.rule.startsWith(`plugin__${id}__`) || parseGroup(rule.rule)?.plugin === id); }
@@ -213,7 +284,17 @@ export class PluginControls {
     const rules = own.map(ruleText).join('; ');
     return this.codeTrusted(`plugin__${id}__x`) ? t('permission rules: {rules}', { rules }) : t('permission rules: {rules} · allow rules do not apply until you trust the current code', { rules });
   }
-  async enable({ id }, options) {
+  // One notice per plugin and reason while this process lives: at startup and after an enable.
+  #toldInvalid = new Set();
+  #contractNotices() {
+    for (const plugin of this.runtime.status().plugins) {
+      if (!plugin.contract_invalid || this.#toldInvalid.has(`${plugin.id}\n${plugin.contract_invalid}`)) continue;
+      this.#toldInvalid.add(`${plugin.id}\n${plugin.contract_invalid}`);
+      this.notice(t('Plugin {id}: its contract cannot be stated ({reason}). It loaded and serves as before, but it cannot be repaired by contract until its author fixes that.', { id: plugin.id, reason: plugin.contract_invalid }));
+    }
+  }
+  async enable(input, options) { try { return await this.#enable(input, options); } finally { try { this.#contractNotices(); } catch {} } }
+  async #enable({ id }, options) {
     await this.runtime.discover();
     const live = this.#live(id);
     if (!live) throw new Error(t('Unknown plugin: {id}', { id }));
@@ -298,7 +379,7 @@ export class PluginControls {
     const records = this.store.list();
     const lines = [t('Trust: {file}', { file: this.store.file }) + (this.store.warning ? ` · ${this.store.warning}` : ''), t('Rules: {file}', { file: this.rules.file }) + (this.rules.warning ? ` · ${this.rules.warning}` : '')];
     if (!records.length) lines.push(t('No trusted plugins.'));
-    for (const item of records) lines.push(t('{mark} {id} · {module} · fingerprint {fingerprint} ({count} files) · {at}\n    project: {project}', { mark: item.project === this.project ? '●' : '○', id: item.id, module: item.module, fingerprint: item.code_fingerprint.slice(0, 12), count: item.files.length, at: item.trusted_at, project: item.project }) + (item.project === this.project ? `\n    ${this.#grantSummary(item.id)}` : ''));
+    for (const item of records) lines.push(t('{mark} {id} · {module} · fingerprint {fingerprint} ({count} files) · {at}\n    project: {project}', { mark: item.project === this.project ? '●' : '○', id: item.id, module: item.module, fingerprint: item.code_fingerprint.slice(0, 12), count: item.files.length, at: item.trusted_at, project: item.project }) + (item.reason === 'contract_repair' ? t(' · recorded by the house for a contract repair (/plugins repairs)') : '') + (item.project === this.project ? `\n    ${this.#grantSummary(item.id)}` : ''));
     return lines.join('\n');
   }
   async untrust({ id }) {
@@ -328,6 +409,128 @@ export class PluginControls {
     return [t('Allow rules of {id} ({scope}): {rules} → {covered}.', { id, scope: this.rules.scope, rules: [...rules].join(', ') || t('no rules'), covered: covered.map(short).join(', ') || t('nothing') }), t('Still asking: {names}.', { names: asking.join(', ') || t('no operations') }),
       ...(denied.length ? [t('Explicitly denied (they win): {names}.', { names: denied.join(', ') })] : []), ...(covered.length && !allowed.length && !denied.length ? [t('Not applying yet: the live code does not match the recorded trust (/plugins enable).')] : [])].join('\n');
   }
+  /** This project's accepted repairs, from the records beside their patches (newest first). */
+  async repairs() {
+    const { items, total } = await readRepairRecords(this.stateDir), lines = [t('Repairs: {dir}', { dir: overlaysDir(this.stateDir) })];
+    if (!items.length) { lines.push(t('No accepted repairs in this project.')); return lines.join('\n'); }
+    if (total > items.length) lines.push(t('Showing the {shown} most recent of {total}.', { shown: items.length, total }));
+    let raw = { plugins: [] }; try { raw = await readRaw(this.project); } catch {}
+    for (const item of items) {
+      const entry = raw.plugins.find(plugin => plugin?.id === item.plugin), record = path.join(item.dir, 'repair.json');
+      const live = typeof entry?.module === 'string' && repairRecordFile(this.stateDir, item.plugin, this.#resolve(entry.module)) === record;
+      const state = item.reverted_at ? t('reverted {at}', { at: item.reverted_at }) : live ? t('live') : t('no longer in use');
+      // The chain: what this repair was accepted on top of (an earlier repair, or the original).
+      const before = item.before_module ?? item.repaired_from, under = typeof before === 'string' ? repairRecordFile(this.stateDir, item.plugin, before) : null;
+      const below = under ? t('on top of repair {fingerprint}', { fingerprint: path.basename(path.dirname(under)).slice(0, 12) }) : t('on top of the original');
+      // The installed original against what the first repair of this chain recorded for it.
+      const { records, complete } = await repairChain(this.stateDir, item.plugin, path.join(item.dir, 'tree', 'x'));
+      const first = complete ? records.at(-1) : null, originalModule = item.original_module ?? (first ? first.before_module ?? first.repaired_from : undefined);
+      const original = typeof originalModule === 'string' && typeof first?.fingerprint_before === 'string' ? await this.#original(originalModule, first.fingerprint_before) : { text: '—' };
+      lines.push(`${item.plugin} · ${item.accepted_at} · ${item.authority === 'signed_act' ? t('signed act') : t('contract kept')} · ${state}`,
+        t('    fingerprint {before} → {after} · {below}', { before: String(item.fingerprint_before ?? '?').slice(0, 12), after: String(item.fingerprint_after ?? '?').slice(0, 12), below }),
+        t('    cases run: {cases}', { cases: Array.isArray(item.cases) && item.cases.length ? item.cases.join('; ') : t('(none)') }),
+        t('    patch: {patch}', { patch: item.patch }),
+        t('    installed original: {state} · {module}', { state: original.text, module: originalModule ?? '?' }));
+    }
+    return lines.join('\n');
+  }
+  /** The acts the human signed in this project's sessions (newest first), and the repair that stands on each. */
+  async acts() {
+    const { items, total } = await readActRecords(this.stateDir), lines = [t('Signed acts: {dir}', { dir: actsDir(this.stateDir) })];
+    if (!items.length) { lines.push(t('No signed acts in this project.')); return lines.join('\n'); }
+    if (total > items.length) lines.push(t('Showing the {shown} most recent of {total}.', { shown: items.length, total }));
+    const { items: repairs } = await readRepairRecords(this.stateDir, { limit: Infinity });
+    const listed = value => Array.isArray(value) && value.length ? value.join('; ') : t('(none)');
+    for (const item of items) {
+      const used = item.act && repairs.find(repair => repair.act?.sha256 === item.act.sha256 && repair.act?.sequence === item.act.sequence && repair.plugin === item.plugin);
+      lines.push(t('{plugin} · {at} · reason: {reason}', { plugin: item.plugin, at: item.signed_at, reason: item.reason ? `«${String(item.reason).slice(0, 300)}»` : t('(none given)') }),
+        t('    surface changed: {items}', { items: listed(item.surface_changed) }),
+        t('    cases added: {added} · removed: {removed} · changed: {changed}', { added: listed(item.cases_added), removed: listed(item.cases_removed), changed: listed(item.cases_changed) }),
+        ...(Array.isArray(item.unfollowed) && item.unfollowed.length ? [t('    code the house cannot follow: {items}', { items: item.unfollowed.map(entry => `${entry?.file}: ${entry?.construct}`).join('; ').slice(0, 600) })] : []),
+        used ? t('    used by the repair accepted at {at} (fingerprint {fingerprint})', { at: used.accepted_at, fingerprint: String(used.fingerprint_after ?? '?').slice(0, 12) }) : t('    no repair stands on it'));
+    }
+    return lines.join('\n');
+  }
+  #serving(id, code) { const live = this.#live(id); return Boolean(code?.code_fingerprint) && live?.state === 'active' && live.module === code.module && live.code_fingerprint === code.code_fingerprint; }
+  /**
+   * Puts the human's original module back in plugins.json (from repaired_from, which every repair of a repair
+   * keeps, so one revert undoes the whole chain), with the same atomic writer /plugins add uses; drops the trust
+   * the house recorded for the repair and reloads. The original's trust is asked the usual way when it has none.
+   * Everything that can refuse is checked before anything is written. If the reload fails after the write,
+   * plugins.json (only if it still holds what revert wrote) and the repair's trust are put back. The overlays
+   * stay as history; their records say reverted.
+   */
+  async revert({ id }, options = {}) {
+    if (this.repair?.busy?.(id)) throw new Error(t('A repair of {id} is in progress in this session; let it be accepted or discarded first.', { id }));
+    const previousBytes = await readFile(this.project).catch(() => null);
+    const raw = await readRaw(this.project), entry = raw.plugins.find(item => item?.id === id);
+    if (!entry) throw new Error(t('{id} is not in {file}.', { id, file: this.project }));
+    if (typeof entry.repaired_from !== 'string') throw new Error(t('{id} has no repair to revert (no repaired_from in {file}).', { id, file: this.project }));
+    const live = this.#live(id); if (live?.builtin) throw new Error(t('Host-reserved plugin: {id}', { id }));
+    const wasActive = live?.state === 'active';
+    // Another active plugin consuming a service this one provides would block the reload: refuse now.
+    const consumers = wasActive ? this.runtime.status().plugins.filter(item => item.id !== id && item.state === 'active' && item.requires?.some(name => live.provides?.includes(name))).map(item => item.id) : [];
+    if (consumers.length) throw new Error(t('Plugin {id} has active consumers ({consumers}); disable them before reverting. Nothing was changed.', { id, consumers: consumers.join(', ') }));
+    const originalPath = this.#resolve(entry.repaired_from);
+    let to;
+    try { const code = await inspectPluginModule(originalPath); to = { module: code.module, code_fingerprint: code.code_fingerprint }; }
+    catch (error) { throw new Error(t('The original module of {id} ({module}) is missing or cannot be read ({reason}). Nothing was changed.', { id, module: originalPath, reason: error.code || error.message })); }
+    const overlayModule = this.#resolve(entry.module);
+    let from = { module: overlayModule, code_fingerprint: null };
+    try { const code = await inspectPluginModule(overlayModule); from = { module: code.module, code_fingerprint: code.code_fingerprint }; } catch {}
+    // Whether the repaired copy is what serves now. By its module path alone: when the overlay was deleted by
+    // hand its fingerprint cannot be read any more, and what serves is in-memory code nobody can review.
+    const servingRepaired = () => { const now = this.#live(id); return now?.state === 'active' && [from.module, overlayModule].includes(now.module); };
+    const { repaired_from: original, ...next } = { ...entry, module: entry.repaired_from };
+    raw.plugins = raw.plugins.map(item => item?.id === id ? next : item);
+    const written = (await writeRaw(this.project, raw))?.hash;
+    // Only the record the house made for this overlay; a record the human made since is theirs.
+    const saved = this.store.find(this.project, id);
+    const trustRemoved = Boolean(saved?.reason === 'contract_repair' && (saved.module === from.module || saved.code_fingerprint === from.code_fingerprint)) && await this.store.revoke(this.project, id);
+    const lines = [trustRemoved ? t('Reverted {id}: {file} points at the original {module} again; the trust the house recorded for the repair was removed.', { id, file: this.project, module: original })
+      : t('Reverted {id}: {file} points at the original {module} again.', { id, file: this.project, module: original })];
+    try {
+      const { entry: current, code } = await this.runtime.inspect(id);
+      if (next.enabled === false) { if (servingRepaired()) await this.runtime.disable(id); }
+      else if (!wasActive) lines.push(t('{id} is not active in this session; /plugins enable {id} loads the installed code.', { id }));
+      else if (trustVerdict(this.store.find(this.project, id), { project: this.project, entry: current, code }).status !== 'trusted' && !this.confirm && !this.trustByFlag) {
+        // No human to ask and no --trust-plugins: the installed code serves this session only, as /plugins enable does.
+        await this.runtime.load(id, { signal: options.signal });
+        lines.push(t('{id}: active only in this session (no remembered trust). In the TUI, /plugins enable {id} asks for confirmation and remembers it; in -p, add --trust-plugins.', { id }));
+      } else {
+        lines.push(await this.#trustAndEnable(id, options));
+        // Declined: the repaired copy must not keep serving under a configuration that no longer names it.
+        if (servingRepaired()) { await this.runtime.disable(id); lines.push(t('The repaired copy no longer serves: {id} waits for your trust in the installed code (/plugins enable {id}).', { id })); }
+      }
+    } catch (error) {
+      throw await this.#revertFailed({ id, from, to, error, previousBytes, written, saved, trustRemoved, wasActive });
+    }
+    // Every repair of the chain under the overlay that served is undone by this revert.
+    const { records } = await repairChain(this.stateDir, id, from.module);
+    for (const record of records) if (!record.reverted_at) await markRepairReverted(record.file).catch(() => {});
+    await this.journal({ type: 'plugin_repair_reverted', source: 'human_session', plugin: id, from, to, trust_removed: trustRemoved, undone: records.map(record => record.fingerprint_after), state: this.#live(id)?.state ?? null });
+    return lines.join('\n');
+  }
+  // The reload after the write failed: plugins.json goes back (only if it is still what revert wrote), the
+  // repair's trust record goes back, and the repaired copy serves again if it stopped. Journaled; returns the error.
+  async #revertFailed({ id, from, to, error, previousBytes, written, saved, trustRemoved, wasActive }) {
+    const reason = String(error?.message ?? error).slice(0, 2000), restored = { plugins_json: false, trust: !trustRemoved, generation: 'kept' };
+    let current = null; try { current = await readFile(this.project); } catch {}
+    if (previousBytes && current && written && createHash('sha256').update(current).digest('hex') === written) {
+      const temporary = path.join(path.dirname(this.project), `.plugins-${randomUUID()}.json`);
+      try { await writeFile(temporary, previousBytes, { mode: 0o644, flag: 'wx' }); await rename(temporary, this.project); restored.plugins_json = true; }
+      catch (failure) { await rm(temporary, { force: true }).catch(() => {}); restored.plugins_json_error = failure.message; }
+    } else restored.plugins_json = 'left_as_edited';
+    if (trustRemoved) { try { await this.store.restore(this.project, id, saved); restored.trust = true; } catch (failure) { restored.trust_error = failure.message; } }
+    try { await this.runtime.discover(); } catch {}
+    if (wasActive && restored.plugins_json === true && !this.#serving(id, from)) {
+      try { await this.runtime.load(id, { expect: { module: from.module, code_fingerprint: from.code_fingerprint } }); restored.generation = 'reloaded'; } catch (failure) { restored.generation = 'failed'; restored.generation_error = failure.message; }
+    }
+    await this.journal({ type: 'plugin_repair_revert_failed', source: 'human_session', plugin: id, from, to, reason, restored });
+    const message = restored.plugins_json === true ? t('The revert of {id} failed while reloading ({reason}). {file} and the repair\'s trust were put back; the repair stays.', { id, reason, file: this.project })
+      : t('The revert of {id} failed while reloading ({reason}). {file} was edited meanwhile and was left as it is; check it with /plugins.', { id, reason, file: this.project });
+    return Object.assign(new Error(message), { code: error?.code, cause: error });
+  }
   async workflow({ mode }) {
     const raw = await readRaw(this.project);
     if (!mode) return t('Chrome workflow: effective {effective} · saved in the project: {saved}', { effective: this.currentWorkflow() || 'auto', saved: raw.chrome_workflow || t('(nothing)') });
@@ -348,6 +551,9 @@ export class PluginControls {
       { name: 'PluginConfigure', description: 'Human shows or changes a configured plugin configuration.', input_schema: object({ id: idInput, set: setInput }, ['id']), run: run('configure') },
       { name: 'PluginTrustList', description: 'Human lists remembered plugin trust records.', input_schema: object(), run: run('trustList') },
       { name: 'PluginUntrust', description: 'Human revokes remembered trust and saved permissions of a plugin in this project.', input_schema: object({ id: idInput }, ['id']), run: run('untrust') },
+      { name: 'PluginRepairs', description: 'Human lists the contract repairs accepted in this project: plugin, when, authority, cases run, patch and whether the installed original changed since.', input_schema: object(), run: run('repairs') },
+      { name: 'PluginActs', description: 'Human lists the acts signed in this project to change a plugin contract: plugin, when, what changed and the reason.', input_schema: object(), run: run('acts') },
+      { name: 'PluginRevert', description: 'Human reverts the last contract repair of a plugin: plugins.json names the replaced module again, the repair trust is removed and the plugin reloads (asking for trust of the original when needed).', input_schema: object({ id: idInput }, ['id']), run: run('revert') },
       { name: 'PluginAllow', description: 'Human saves which plugin operations are authorized without asking. Explicit denials still win.', input_schema: object({ id: idInput, operations: { type: 'array', items: { type: 'string', maxLength: 128 }, minItems: 1, maxItems: 64 } }, ['id', 'operations']), run: run('allow') },
       { name: 'ChromeWorkflow', description: 'Human shows or saves the Chrome entry workflow (auto|raw) for this project.', input_schema: object({ mode: { enum: ['auto', 'raw'] } }), run: run('workflow') },
     ];