@milpa/comal 0.2.6 → 0.2.8

package/src/plugin-repair.mjs

@@ -0,0 +1,981 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile, writeFile, mkdir, lstat, rename, rm, symlink, readdir, stat as statFile, open as openFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { PLUGIN_REPAIR_OPERATION_NAMES } from './operations.mjs';
+import path from 'node:path';
+import { readPluginConfig, writePluginConfigRaw, inspectPluginModule, parsePluginConfig } from './plugin-config.mjs';
+import { processIdentity, processDead } from './process-lock.mjs';
+import { configDigest } from './plugin-trust.mjs';
+import { openCandidate, readCandidate, verifyCandidate, verifyPlacement, candidateDiff, discardCandidate } from './plugin-workbench.mjs';
+import { defaultStateDir } from './compat.mjs';
+import { validateCases, caseDigest, evaluateCase, compareContracts } from './plugin-contract.mjs';
+import { runCandidate, hostServiceStandIns } from './plugin-candidate-runner.mjs';
+import { t } from './i18n/index.mjs';
+
+// Repair by contract (docs/superpowers/specs/2026-11-10-house-findings-design.md, «Repair: by contract»):
+// the five operations the model drives. Who establishes what:
+// - a case result is obtained by THIS process calling the live operation through the model's own
+//   house binding (permissions, guards, receipts), and evaluated by the house (evaluateCase);
+// - the contract that must be kept is runtime.contract(id) (live) against the contract the runtime
+//   staged from the overlay (admit), both computed in this process;
+// - the candidate's pre-flight report (PluginRepairTest) is the candidate's own account: shown to the
+//   model as advice, never read by PluginRepairAccept;
+// - a change of contract needs an act signed by the human (a sealed plugin_contract_act row).
+// Model-facing descriptions and errors are English; what a human reads goes through t().
+
+export const PLUGIN_REPAIR_OPERATIONS = PLUGIN_REPAIR_OPERATION_NAMES;
+// How long PluginRepairTest lets a candidate's separate process import, activate and replay: 20 s, or
+// COMAL_PLUGIN_CANDIDATE_TIMEOUT_MS (a positive whole number of ms; anything above 120000 counts as
+// 120000). Read once, by the CLI.
+export const CANDIDATE_TIMEOUT_CAP_MS = 120000;
+export function candidateTimeoutMs(env = process.env) {
+  const raw = String(env.COMAL_PLUGIN_CANDIDATE_TIMEOUT_MS ?? '').trim();
+  if (!/^[1-9]\d*$/.test(raw)) return 20000;
+  return Number(raw) <= CANDIDATE_TIMEOUT_CAP_MS ? Number(raw) : CANDIDATE_TIMEOUT_CAP_MS;
+}
+// The pending marker of an Accept: one per plugin, <stateDir>/plugin-repair-pending/<id>.json, created
+// exclusively and removed only by the Accept that owns it. The single file of the previous release
+// (<stateDir>/plugin-repair-pending.json) is still read for one release: recovered, then deleted.
+const PENDING = 'plugin-repair-pending.json', PENDING_DIR = 'plugin-repair-pending';
+const pendingMarker = (stateDir, id) => path.join(stateDir, PENDING_DIR, `${id}.json`);
+/** The real path of a location that may not exist yet: its nearest existing ancestor resolved, plus the rest. */
+export function realLocation(location) {
+  let ancestor = path.resolve(location); const suffix = [];
+  for (;;) {
+    try { return path.join(realpathSync(ancestor), ...suffix); }
+    catch { const parent = path.dirname(ancestor); if (parent === ancestor) return path.resolve(location); suffix.unshift(path.basename(ancestor)); ancestor = parent; }
+  }
+}
+const sameOwner = (a, b) => Boolean(a && b) && a.pid === b.pid && (a.start ?? null) === (b.start ?? null) && (a.boot ?? null) === (b.boot ?? null) && (a.host ?? null) === (b.host ?? null);
+const SHA = /^[0-9a-f]{64}$/;
+const ID = { type: 'string', pattern: '^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$', maxLength: 24 };
+const UUID = { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' };
+const sha256 = value => createHash('sha256').update(value).digest('hex');
+const ref = row => row?.audit && Number.isInteger(row.audit.sequence) && typeof row.audit.sha256 === 'string' ? { sequence: row.audit.sequence, sha256: row.audit.sha256 } : null;
+// A refusal is an ordinary operation result for the model: a thrown error with a code and what to do next.
+const refusal = (code, message, next, details = {}) => Object.assign(new Error(`${message} Next: ${next}`), { code, details: { ...details, next_action: next } });
+// Refusals before the handler ran (permission, plan mode, guard, unavailable, stale catalogue, invalid input).
+const NOT_RUN = /^(HOUSE_(REFUSED|GUARD|STALE|AUTHORITY_CHANGED|SURFACE_CHANGED|INPUT_SCHEMA|PERMISSION_DENIED)|GOVERNANCE_REFUSED|TOOL_PACK_REQUIRED)$/;
+
+// A contract as the act and the accepted row name it: the surface digest and every case's digest.
+const summary = contract => ({ surface_digest: contract.surface_digest, cases: contract.cases.map(item => ({ name: item.name, digest: item.digest })) });
+const sameContract = (a, b) => a.surface_digest === b.surface_digest && JSON.stringify(a.cases.map(item => item.digest).sort()) === JSON.stringify(b.cases.map(item => item.digest).sort());
+const listed = items => items.length ? items.join(', ') : t('(none)');
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const canonical = value => Array.isArray(value) ? value.map(canonical) : plain(value) ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+const ITEM = 600, CARD = 24000;
+// What PluginRepairAccept's answer shows of each case run: at most CASE_OUTPUT bytes per case and
+// CASE_OUTPUT_TOTAL for all of them. The journal's rows keep digests and receipts, never these.
+const CASE_OUTPUT = 4 * 1024, CASE_OUTPUT_TOTAL = 16 * 1024;
+const bytesOf = text => Buffer.byteLength(text);
+function cutBytes(text, limit) {
+  let out = text.slice(0, Math.max(0, limit));
+  while (bytesOf(out) > limit) out = out.slice(0, out.length - Math.max(1, Math.ceil((bytesOf(out) - limit) / 4)));
+  return out;
+}
+// One case run as the model sees it: the returned value (parsed when it is JSON), or what it threw. A value
+// that does not fit is cut to the text that does and marked output_truncated.
+function caseShown(result, budget) {
+  if (result.status === 'threw') {
+    const message = cutBytes(String(result.message ?? ''), Math.min(CASE_OUTPUT, budget.left)); budget.left -= bytesOf(message);
+    return { threw: { ...(result.code ? { code: result.code } : {}), message }, ...(message.length < String(result.message ?? '').length ? { output_truncated: true } : {}) };
+  }
+  if (result.status !== 'returned') return {};
+  let value = result.output, text;
+  if (typeof value === 'string') { try { value = JSON.parse(value); } catch {} }
+  try { text = JSON.stringify(value) ?? 'null'; } catch { text = String(result.output); value = text; }
+  const limit = Math.min(CASE_OUTPUT, budget.left);
+  if (bytesOf(text) <= limit) { budget.left -= bytesOf(text); return { output: value }; }
+  const cut = cutBytes(text, limit); budget.left -= bytesOf(cut);
+  return { ...(cut ? { output: cut } : {}), output_truncated: true };
+}
+// One side of a change as compact canonical JSON, at most ITEM chars.
+const compact = value => { const text = JSON.stringify(canonical(value ?? null)); return text.length > ITEM ? { text: `${text.slice(0, ITEM)}… [truncated]`, cut: true } : { text, cut: false }; };
+// What an entry of surface_changed names, on one side of the comparison.
+function surfaceSide(contract, item) {
+  const match = /^operation:(.+?):(.+)$/.exec(item), surface = contract.surface ?? {};
+  if (!match) return { present: Object.hasOwn(surface, item), value: surface[item] };
+  const op = (surface.operations ?? []).find(entry => entry.name === match[1]), field = match[2];
+  if (field === 'added' || field === 'removed') return { present: Boolean(op), value: op };
+  if (!op) return { present: false };
+  if (field.startsWith('origin.')) return { present: Boolean(op.origin) && Object.hasOwn(op.origin, field.slice(7)), value: op.origin?.[field.slice(7)] };
+  return { present: Object.hasOwn(op, field), value: op[field] };
+}
+const caseSide = (contract, name) => { const found = contract.cases.find(item => item.name === name); return found ? { present: true, value: { input: found.input, expect: found.expect } } : { present: false }; };
+
+// The card the human reads before signing a change of contract (default No): every change with its
+// before and after. Returns the text and how many items had to be truncated.
+function actCard({ plugin, comparison, reason, files, before, after, saved, unfollowed = [] }) {
+  let truncated = 0;
+  const detail = (name, sides) => {
+    const lines = [`  • ${name}`]; let cut = false;
+    for (const [label, side] of sides) if (side.present) { const shown = compact(side.value); cut ||= shown.cut; lines.push(`    ${t(label, { value: shown.text })}`); }
+    if (cut) truncated++;
+    return lines;
+  };
+  const sides = (pick, name) => [['before: {value}', pick(before, name)], ['after: {value}', pick(after, name)]];
+  const lines = [
+    comparison.kept ? t('Plugin {plugin}: the repair keeps what it promises, but it holds code the house cannot follow by reading it. Sign only if you reviewed that code.', { plugin })
+      : t('Plugin {plugin}: the repair changes what it promises. Sign only if you accept the new contract.', { plugin }),
+    t('Surface changed: {list}', { list: listed(comparison.surface_changed) }), ...comparison.surface_changed.flatMap(item => detail(item, sides(surfaceSide, item))),
+    t('Cases removed: {list}', { list: listed(comparison.cases_removed) }), ...comparison.cases_removed.flatMap(name => detail(name, sides(caseSide, name))),
+    t('Cases changed: {list}', { list: listed(comparison.cases_changed) }), ...comparison.cases_changed.flatMap(name => detail(name, sides(caseSide, name))),
+    t('Cases added: {list}', { list: listed(comparison.cases_added) }), ...comparison.cases_added.flatMap(name => detail(name, sides(caseSide, name))),
+    t('Code the house cannot follow: {list}', { list: listed(unfollowed.map(item => `${item.file}: ${item.construct}`)) }),
+    t("The model's reason: {reason}", { reason: reason || t('(none given)') }),
+    t('Files in the patch: {list}', { list: listed(files) }),
+  ];
+  let text = lines.join('\n');
+  if (text.length > CARD) { text = text.slice(0, CARD); truncated++; }
+  const trailer = [...(truncated && saved ? [t('{count} item(s) truncated; the full contracts before and after are in {before} and {after}.', { count: truncated, before: saved.before, after: saved.after })] : []),
+    t('Yes signs the act and the repaired plugin is published and checked; No (the default) leaves everything as it is.')];
+  return { text: [text, ...trailer].join('\n'), truncated };
+}
+
+// A private file written whole or not at all: temporary file in the same directory, fsync, rename.
+async function writeAtomic(file, data, mode = 0o600) {
+  const temporary = path.join(path.dirname(file), `.${path.basename(file)}-${randomUUID()}`);
+  try {
+    const handle = await openFile(temporary, 'wx', mode);
+    try { await handle.writeFile(data); await handle.sync(); } finally { await handle.close(); }
+    await rename(temporary, file);
+  } catch (error) { await rm(temporary, { force: true }).catch(() => {}); throw error; }
+}
+
+const MARKER_BYTES = 2 * 1024 * 1024;
+const sameJson = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+
+// The edit an Accept makes, and only it: the same configuration except that the marker's plugin entry
+// points at an overlay under <stateDir>/plugin-overlays/<id>/ and remembers the module it replaced.
+function repairShaped({ previous, current, plugin, pluginsFile, stateDir }) {
+  let before, after;
+  try { before = JSON.parse(previous.toString('utf8')); after = JSON.parse(current.toString('utf8')); parsePluginConfig(previous, pluginsFile); parsePluginConfig(current, pluginsFile); }
+  catch { return 'not_a_plugin_config'; }
+  const { plugins: was, ...restBefore } = before, { plugins: now, ...restAfter } = after;
+  if (!sameJson(restBefore, restAfter) || !Array.isArray(was) || !Array.isArray(now) || was.length !== now.length) return 'not_repair_shaped';
+  // Real paths on both sides: Accept writes the overlay's real module path, and the state directory may be reached through a link.
+  const home = path.join(realLocation(stateDir), 'plugin-overlays', plugin) + path.sep;
+  let repaired = 0;
+  for (let index = 0; index < was.length; index++) {
+    const a = was[index], b = now[index];
+    if (a?.id !== plugin) { if (!sameJson(a, b)) return 'not_repair_shaped'; continue; }
+    repaired++;
+    // repaired_from names the human's original: kept as it was when the entry was already a repair.
+    if (b?.id !== plugin || b.repaired_from !== (a.repaired_from ?? a.module) || typeof b.module !== 'string' || !realLocation(path.resolve(path.dirname(pluginsFile), b.module)).startsWith(home)) return 'not_repair_shaped';
+    const { module: _m, repaired_from: _r, ...keepA } = a, { module: _n, repaired_from: _s, ...keepB } = b;
+    if (!sameJson(keepA, keepB)) return 'not_repair_shaped';
+  }
+  return repaired === 1 ? null : 'not_repair_shaped';
+}
+
+/**
+ * One pending marker, as startup recovery treats it. Nothing happens while the marker's owner is alive (its
+ * Accept is still running). With the owner dead:
+ * - a repair that completed (the marker says so, or `completed(marker)` finds it in its journal) is kept;
+ * - otherwise the repair's trust record (reason contract_repair, for this marker's overlay) is removed and the
+ *   record that was there before is put back, whatever happened to plugins.json since: a repair with no sealed
+ *   acceptance must not keep trust;
+ * - and plugins.json is put back only when it is still exactly what that Accept wrote AND the change is the
+ *   repair's shape; its mode is kept. Anything else (missing, edited since) is left alone.
+ * The marker is then removed. A corrupt, oversized or ownerless marker is removed, never thrown. Returns null
+ * when there is no marker, when its owner is alive, or when it belongs to another plugins.json.
+ */
+async function recoverMarker(marker, { stateDir, pluginsFile, trustStore, completed, expectPlugin } = {}) {
+  const corrupt = async error => { await rm(marker, { force: true }).catch(() => {}); return { recovered: false, restored: false, corrupt: true, error: String(error?.message ?? error) }; };
+  let info;
+  try { info = await statFile(marker); } catch (error) { if (error.code === 'ENOENT') return null; return corrupt(error); }
+  if (!info.isFile() || info.size > MARKER_BYTES) return corrupt('the marker is not a regular file of at most 2 MB');
+  let pending, previous;
+  try {
+    pending = JSON.parse(await readFile(marker, 'utf8'));
+    if (!plain(pending) || typeof pending.plugin !== 'string' || typeof pending.plugins_file !== 'string' || typeof pending.previous_bytes !== 'string' || !SHA.test(pending.previous_sha256 ?? '') || !SHA.test(pending.written_sha256 ?? '') || !plain(pending.owner) || !Number.isSafeInteger(pending.owner.pid)) throw new Error('invalid marker');
+    if (expectPlugin !== undefined && pending.plugin !== expectPlugin) throw new Error('the marker does not name the plugin of its file');
+    previous = Buffer.from(pending.previous_bytes, 'base64');
+    if (sha256(previous) !== pending.previous_sha256) throw new Error('the previous bytes do not match their hash');
+  } catch (error) { return corrupt(error); }
+  if (realLocation(pending.plugins_file) !== realLocation(pluginsFile)) return null;
+  if (!processDead(pending.owner)) return null;   // its Accept is still running: never touch it
+  const result = { recovered: true, plugin: pending.plugin, candidate: pending.candidate ?? null, session: pending.session ?? null, overlay: pending.overlay ?? null, plugins_file: pluginsFile };
+  let done = pending.completed === true;
+  if (!done && typeof completed === 'function') { try { done = (await completed(pending)) === true; } catch {} }
+  if (done) { await rm(marker, { force: true }); return { ...result, restored: false, reason: 'completed' }; }
+  // The repair's trust record replaced the human's one for the code it replaced: put that one back. The crash
+  // may have come between the trust write and the sealed row, so this does not depend on plugins.json.
+  const restoreTrust = async () => {
+    try {
+      await trustStore?.load?.();
+      const now = trustStore?.find?.(pluginsFile, pending.plugin);
+      if (trustStore && now?.reason === 'contract_repair' && now.code_fingerprint === pending.overlay_fingerprint) { await trustStore.restore(pluginsFile, pending.plugin, pending.previous_trust ?? undefined); return 'restored'; }
+      return 'unchanged';
+    } catch (error) { return `failed: ${String(error.message).slice(0, 200)}`; }
+  };
+  let current = null, mode = 0o600;
+  try { current = await readFile(pluginsFile); mode = (await statFile(pluginsFile)).mode & 0o777; } catch {}
+  const why = !current ? 'missing' : sha256(current) !== pending.written_sha256 ? 'edited_since' : repairShaped({ previous, current, plugin: pending.plugin, pluginsFile, stateDir });
+  if (why) { const trust = await restoreTrust(); await rm(marker, { force: true }); return { ...result, restored: false, reason: why, trust }; }
+  await writeAtomic(pluginsFile, previous, mode);
+  const trust = await restoreTrust();
+  await rm(marker, { force: true });
+  return { ...result, restored: true, trust };
+}
+
+/**
+ * At startup, before plugins load: every repair that was accepting when its process died left a marker
+ * (<stateDir>/plugin-repair-pending/<id>.json, or the previous release's single plugin-repair-pending.json).
+ * Each is treated as recoverMarker says. Returns one result per marker that was acted on. A marker whose
+ * recovery throws is NOT removed: its result says { failed: true, marker_kept: true, error } and the others
+ * still run.
+ */
+export async function recoverPendingRepairs({ stateDir, pluginsFile, trustStore, completed } = {}) {
+  const state = realLocation(stateDir), results = [];
+  const each = async (marker, expectPlugin) => {
+    try { const result = await recoverMarker(marker, { stateDir: state, pluginsFile, trustStore, completed, expectPlugin }); if (result) results.push(result); }
+    catch (error) { results.push({ recovered: false, restored: false, failed: true, marker_kept: true, marker, ...(expectPlugin ? { plugin: expectPlugin } : {}), error: String(error?.message ?? error).slice(0, 2000) }); }
+  };
+  await each(path.join(state, PENDING));
+  const dir = path.join(state, PENDING_DIR);
+  let info = null; try { info = await lstat(dir); } catch {}
+  if (info?.isDirectory()) {
+    for (const name of (await readdir(dir)).sort()) { const match = /^(.+)\.json$/.exec(name); if (match && PLUGIN_DIR.test(match[1])) await each(path.join(dir, name), match[1]); }
+  }
+  return results;
+}
+/** The first result of recoverPendingRepairs, or null: the shape of the previous release's single marker. */
+export async function recoverPendingRepair(options) { return (await recoverPendingRepairs(options))[0] ?? null; }
+
+// The human's view (/plugins repairs, /plugins acts): small records the house writes beside its work.
+// They are informational. The authority stays the journal and the trust store, and /plugins revert works
+// from plugins.json's repaired_from, never from these files.
+//   <stateDir>/plugin-overlays/<id>/<fingerprint>/repair.json   one accepted repair (beside repair.patch)
+//   <stateDir>/plugin-acts/<id>/<time>-<uuid>.json              one act the human signed (it outlives a rollback)
+export const REPAIR_RECORD = 'repair.json';
+export const RECORD_LIMIT = 200;
+const RECORD_BYTES = 256 * 1024;
+const FINGERPRINT = /^[0-9a-f]{64}$/;
+export const overlaysDir = stateDir => path.join(stateDir, 'plugin-overlays');
+export const actsDir = stateDir => path.join(stateDir, 'plugin-acts');
+const PLUGIN_DIR = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+async function entries(dir) { try { return await readdir(dir, { withFileTypes: true }); } catch { return []; } }
+async function smallJson(file) {
+  try { const info = await lstat(file); if (!info.isFile() || info.size > RECORD_BYTES) return null; const value = JSON.parse(await readFile(file, 'utf8')); return plain(value) ? value : null; } catch { return null; }
+}
+// Newest first, at most `limit`; `total` says how many there were.
+const newest = (items, key, limit) => ({ items: items.sort((a, b) => String(b[key] ?? '').localeCompare(String(a[key] ?? ''))).slice(0, limit), total: items.length });
+/** The accepted repairs of this project (each overlay with a repair.json), newest first. */
+export async function readRepairRecords(stateDir, { limit = RECORD_LIMIT } = {}) {
+  const items = [];
+  for (const plugin of await entries(overlaysDir(stateDir))) {
+    if (!plugin.isDirectory() || !PLUGIN_DIR.test(plugin.name)) continue;
+    for (const overlay of await entries(path.join(overlaysDir(stateDir), plugin.name))) {
+      if (!overlay.isDirectory() || !FINGERPRINT.test(overlay.name)) continue;
+      const dir = path.join(overlaysDir(stateDir), plugin.name, overlay.name), record = await smallJson(path.join(dir, REPAIR_RECORD));
+      if (record && record.plugin === plugin.name) items.push({ ...record, dir, patch: path.join(dir, 'repair.patch') });
+    }
+  }
+  return newest(items, 'accepted_at', limit);
+}
+/** The acts the human signed in this project's sessions, newest first. */
+export async function readActRecords(stateDir, { limit = RECORD_LIMIT } = {}) {
+  const items = [];
+  for (const plugin of await entries(actsDir(stateDir))) {
+    if (!plugin.isDirectory() || !PLUGIN_DIR.test(plugin.name)) continue;
+    for (const file of await entries(path.join(actsDir(stateDir), plugin.name))) {
+      if (!file.isFile() || !file.name.endsWith('.json') || file.name.startsWith('.')) continue;
+      const record = await smallJson(path.join(actsDir(stateDir), plugin.name, file.name));
+      if (record && record.plugin === plugin.name) items.push({ ...record, file: path.join(actsDir(stateDir), plugin.name, file.name) });
+    }
+  }
+  return newest(items, 'signed_at', limit);
+}
+/** The repair.json of the overlay a module path lives in, or null when the module is not an overlay. */
+export function repairRecordFile(stateDir, id, module) {
+  const relative = path.relative(path.join(overlaysDir(stateDir), id), path.resolve(module)).split(path.sep);
+  return relative.length > 2 && FINGERPRINT.test(relative[0]) && relative[1] === 'tree' ? path.join(overlaysDir(stateDir), id, relative[0], REPAIR_RECORD) : null;
+}
+export async function readRepairRecord(file) { return file ? smallJson(file) : null; }
+/**
+ * The chain of repairs under a live overlay, newest first: each record's `before_module` is what was live
+ * when it was accepted, an earlier overlay or the original. The last one is the first repair, whose
+ * `fingerprint_before` is the original's fingerprint as it was then. `complete` is false when a record is
+ * missing midway. Bounded, and a cycle stops it.
+ */
+export async function repairChain(stateDir, id, module, { limit = 32 } = {}) {
+  const records = [], seen = new Set();
+  let file = repairRecordFile(stateDir, id, module);
+  while (file && !seen.has(file) && records.length < limit) {
+    seen.add(file);
+    const record = await readRepairRecord(file);
+    if (!record) return { records, complete: false };
+    records.push({ ...record, file });
+    const before = record.before_module ?? record.repaired_from;
+    if (typeof before !== 'string') return { records, complete: false };
+    file = repairRecordFile(stateDir, id, before);
+  }
+  return { records, complete: Boolean(records.length) && !file };
+}
+/** History is kept: a reverted repair's record says when. */
+export async function markRepairReverted(file, at = new Date().toISOString()) {
+  const record = await readRepairRecord(file); if (!record) return false;
+  await writeAtomic(file, JSON.stringify({ ...record, reverted_at: at }, null, 2) + '\n'); return true;
+}
+
+export class PluginRepair {
+  #sessions = new Map();   // sessionId -> { reproduced: Map<plugin, Map<digest, entry>>, open: Map<candidateId, state>, acts: [] }
+  #watch = new Map();      // parent invocation id -> sealed house_receipt rows of its nested calls
+  #busy = new Set();
+  #running = new Map();    // plugin -> the promise of its running Accept
+  #standing = new Map();   // plugin -> the verification standing of one Accept's step 6 (in memory only)
+
+  /**
+   * runtime: PluginRuntime; binding: the house binding of the model's tool calls (actor root-agent);
+   * recorder: FindingRecorder or () => FindingRecorder; trustStore: { find, trust, restore };
+   * policy: PermissionPolicy (candidate write roots); confirm(name, input, options) → strict boolean, or
+   * undefined when no human is present; append(row) → sealed row in the session journal; completed(marker) →
+   * whether the journal holds the sealed acceptance of a dead process's pending marker (as startup recovery asks);
+   * releaseFence({ plugin, accepted, sessionId, invocation_id }) → the work steps the accepted repair released
+   * ([{ task_id, step_id, operation }], see releaseRepairedSteps in work-plan.mjs), or undefined where there is no work plan.
+   */
+  constructor({ runtime, binding, recorder, trustStore, policy, confirm, cwd = process.cwd(), stateDir, append, trustByFlag = false, runner, timeoutMs = 20000, completed, releaseFence } = {}) {
+    if (!runtime || !binding?.execute || typeof append !== 'function') throw new TypeError('PluginRepair requires a runtime, a house binding and append(row).');
+    Object.assign(this, { runtime, binding, recorder, trustStore, policy, confirm, cwd, stateDir, append, trustByFlag, runner, timeoutMs, completed, releaseFence });
+  }
+
+  /** The host's sealed house rows: nested receipts of a repair operation are matched to it here. */
+  observe(row) {
+    if (row?.type !== 'house_receipt' || typeof row.parent_invocation_id !== 'string') return;
+    this.#watch.get(row.parent_invocation_id)?.push(row);
+  }
+
+  /**
+   * While Accept runs a published repair's cases (a contract kept, or a change the human signed an act for): what the host's rule gate needs to let the saved rules of
+   * the previous generation apply. Only for a call nested directly under that Accept invocation; undefined
+   * for every other call, and once step 6 ends (success, rollback or throw).
+   */
+  standing(id, invocation) {
+    const entry = this.#standing.get(id);
+    if (!entry || typeof invocation?.parent_invocation_id !== 'string' || invocation.parent_invocation_id !== entry.invocation) return undefined;
+    return structuredClone({ module: entry.module, code_fingerprint: entry.code_fingerprint, config_sha256: entry.config_sha256, previous: entry.previous });
+  }
+
+  /** Whether a repair of `id` is in progress: an open candidate in a session of this process, or an Accept running. */
+  busy(id) { return this.#busy.has(id) || [...this.#sessions.values()].some(session => [...session.open.values()].some(state => state.plugin === id)); }
+
+  #recorder() { return typeof this.recorder === 'function' ? this.recorder() : this.recorder; }
+  #session(id) {
+    if (!this.#sessions.has(id)) this.#sessions.set(id, { reproduced: new Map(), open: new Map(), acts: [] });
+    return this.#sessions.get(id);
+  }
+  async #row(row, options) { return this.append({ source: 'plugin_repair', ...(options?.invocation_id ? { invocation_id: options.invocation_id } : {}), ...row }); }
+
+  // Only the model's own binding may drive a repair: its calls re-enter the house as that same actor.
+  #caller(options) {
+    const own = this.binding.identity?.();
+    if (own && (options?.actor?.id !== own.actor.id || options?.actor?.kind !== own.actor.kind || options?.sessionId !== own.session_id)) {
+      throw refusal('REPAIR_ACTOR', 'Plugin repair is available to the root agent of this session only.', 'Ask the root agent to run the repair.');
+    }
+    return this.#session(options?.sessionId);
+  }
+
+  async #configured(id) {
+    let source;
+    try { source = await readPluginConfig(this.runtime.file, { missing: true }); }
+    catch (error) { throw refusal('REPAIR_NOT_CONFIGURED', `plugins.json cannot be read: ${error.message}`, 'Ask the human to fix plugins.json.'); }
+    const entry = source.entries.find(item => item.id === id);
+    const live = this.runtime.status().plugins.find(item => item.id === id);
+    if (!entry || !live || live.builtin) throw refusal('REPAIR_NOT_CONFIGURED', `Plugin ${id} is not a configured local plugin of this project.`, 'Use PluginStatus to see the configured plugins.');
+    const contract = this.runtime.contract(id);
+    if (!contract || live.state !== 'active') throw refusal('REPAIR_NOT_LIVE', `Plugin ${id} is not active, so it has no live contract to keep.`, 'Enable the plugin first; a repair starts from the plugin that is serving.');
+    // A contract that cannot be stated cannot be kept: there is nothing for the house to compare a repair with.
+    if (contract.invalid) throw refusal('REPAIR_CONTRACT_INVALID', `The contract of plugin ${id} cannot be stated (${contract.invalid}), so the house cannot tell whether a repair keeps it.`, 'Tell the human: the plugin\'s author must fix its cases or its operation schemas (plain JSON only) before it can be repaired by contract.');
+    return { source, entry, live, contract };
+  }
+
+  /**
+   * call(operation, input): the live operation through the model's house binding, as a tool call of the
+   * model nested under the repair operation. { status: 'returned', output } | { status: 'threw', code,
+   * message } | { status: 'not_run', reason }, each with the sealed receipt reference when there is one.
+   */
+  async #call(name, input, options) {
+    const parent = options?.invocation_id, seen = [];
+    if (parent) this.#watch.set(parent, seen);
+    let outcome;
+    try { outcome = { status: 'returned', output: await this.binding.execute(name, structuredClone(input), { signal: options?.signal }) }; }
+    catch (error) {
+      if (options?.signal?.aborted) throw error;
+      const receipt = seen.findLast(row => row.operation === name);
+      const notRun = receipt ? receipt.status === 'refused' : NOT_RUN.test(String(error?.code ?? ''));
+      outcome = notRun ? { status: 'not_run', reason: String(error?.message ?? error).slice(0, 2000), ...(error?.code ? { code: error.code } : {}) } : { status: 'threw', code: typeof error?.code === 'string' ? error.code : undefined, message: String(error?.message ?? error).slice(0, 2000) };
+    } finally { if (parent) this.#watch.delete(parent); }
+    const receipt = seen.findLast(row => row.operation === name);
+    return { ...outcome, receipt: ref(receipt) };
+  }
+
+  async reproduce({ plugin, case: proposed }, options) {
+    const session = this.#caller(options);
+    const { contract, live } = await this.#configured(plugin);
+    let item;
+    try { [item] = validateCases([proposed], contract.surface.operations.filter(op => op.audience !== 'human').map(op => op.name)); }
+    catch (error) { throw refusal('REPAIR_CASE_INVALID', error.message, 'State the case as { name, operation, input, expect } naming one of the plugin\'s operations.'); }
+    const digest = caseDigest(item), result = await this.#call(`plugin__${plugin}__${item.operation}`, item.input, options);
+    const verdict = result.status === 'not_run' ? { pass: false, reason: `Not run: ${result.reason}` } : evaluateCase(item, result);
+    const shown = { status: result.status, ...(result.status === 'returned' ? { output: result.output } : result.status === 'threw' ? { code: result.code, message: result.message } : { reason: result.reason }), pass: verdict.pass, ...(verdict.reason ? { reason: verdict.reason } : {}) };
+    // Only a case that ran and failed is a broken promise. One that passes, or that the house could not
+    // run (a permission refusal, plan mode), reproduces nothing and is not remembered.
+    const reproduced = result.status !== 'not_run' && !verdict.pass;
+    let finding;
+    if (reproduced) {
+      const recorder = this.#recorder();
+      finding = await recorder?.emit({ owner: `plugin:${plugin}`, owner_basis: 'rule:case_failed', kind: 'contract_mismatch', code: 'CASE_FAILED',
+        where: { operation: `plugin__${plugin}__${item.operation}`, case: item.name, case_digest: digest }, evidence: result.receipt ? [result.receipt] : [] });
+      if (finding) recorder.hold(finding.id);
+      if (!session.reproduced.has(plugin)) session.reproduced.set(plugin, new Map());
+      const known = session.reproduced.get(plugin).get(digest);
+      session.reproduced.get(plugin).set(digest, { case: item, digest, fingerprint: live.code_fingerprint, receipt: result.receipt, finding: known?.finding ?? finding?.id ?? null, findings: [...(known?.findings ?? []), ...(finding ? [finding.id] : [])] });
+    }
+    await this.#row({ type: 'plugin_case_reproduced', plugin, case: item.name, case_digest: digest, operation: item.operation, status: result.status, pass: verdict.pass, ...(verdict.reason ? { reason: verdict.reason.slice(0, 2000) } : {}), receipt: result.receipt, ...(finding ? { finding: finding.id } : {}) }, options);
+    return { reproduced, result: shown, ...(finding ? { finding: finding.id } : {}), case_digest: digest,
+      next_action: reproduced ? `The promise is broken and recorded. Open a candidate with PluginRepairOpen {"plugin":"${plugin}"}, fix the code and add this case to the plugin's cases.` : result.status === 'not_run' ? 'The house could not run the case; nothing was reproduced.' : 'The live plugin keeps this promise; there is nothing to repair for this case.' };
+  }
+
+  // The state directory by its real path, resolved once: overlays are recorded by real path (the inspector
+  // resolves modules), and every comparison with them must be on the same footing.
+  #stateReal;
+  get #state() { return this.#stateReal ??= realLocation(path.resolve(this.cwd, this.stateDir ?? defaultStateDir(this.cwd))); }
+
+  // No other Accept may hold this plugin: a marker whose owner is alive (another Comal process) refuses; one
+  // left by a dead process is recovered here as at startup, and what it restored is found by the base checks.
+  async #markerFree(plugin, options) {
+    const project = this.runtime.file, own = pendingMarker(this.#state, plugin), legacy = path.join(this.#state, PENDING);
+    for (const file of [own, legacy]) {
+      let result = null;
+      try { result = await recoverMarker(file, { stateDir: this.#state, pluginsFile: project, trustStore: this.trustStore, completed: this.completed, ...(file === own ? { expectPlugin: plugin } : {}) }); }
+      catch (error) { throw refusal('REPAIR_BUSY_ELSEWHERE', `An interrupted repair of plugin ${plugin} could not be recovered: ${error.message}`, 'Report the reason; restart Comal to recover it.'); }
+      if (result) await this.#row({ type: 'plugin_repair_recovered', ...result }, options).catch(() => {});
+      let held = null;
+      try { held = JSON.parse(await readFile(file, 'utf8')); } catch (error) { if (error.code === 'ENOENT') continue; held = {}; }
+      // The previous release's single file names one plugin of one plugins.json; another's does not concern this Accept.
+      if (file === legacy && (held?.plugin !== plugin || typeof held.plugins_file !== 'string' || realLocation(held.plugins_file) !== realLocation(project))) continue;
+      throw refusal('REPAIR_BUSY_ELSEWHERE', `Another Comal process is accepting a repair of plugin ${plugin} (pid ${held?.owner?.pid ?? 'unknown'}).`, 'Wait for it to finish, then reproduce the case again: the plugin may already be repaired.');
+    }
+  }
+  #writes(options) { if (options?.mode === 'plan') throw refusal('REPAIR_PLAN_MODE', 'Plan mode is read-only: a repair changes files and the running plugin.', 'Leave plan mode to repair the plugin.'); }
+  #candidate(session, candidateId) {
+    const state = session.open.get(candidateId);
+    if (!state) throw refusal('REPAIR_UNKNOWN_CANDIDATE', `No open candidate ${candidateId} in this session.`, 'Use the candidate id that PluginRepairOpen returned, or open a new one.');
+    return state;
+  }
+
+  async open({ plugin }, options) {
+    const session = this.#caller(options); this.#writes(options);
+    const reproduced = session.reproduced.get(plugin);
+    if (!reproduced?.size) throw refusal('REPAIR_NOTHING_REPRODUCED', `No broken promise of plugin ${plugin} was reproduced in this session.`, 'State the failing use case with PluginRepairReproduce first; a repair is built on a case the house saw fail.');
+    const already = [...session.open.values()].find(item => item.plugin === plugin);
+    if (already) throw refusal('REPAIR_ALREADY_OPEN', `Plugin ${plugin} already has an open candidate (${already.candidateId}).`, 'Test, accept or discard that candidate first.', { candidate: already.candidateId, directory: already.root });
+    if (typeof this.policy?.addCandidateRoot !== 'function') throw refusal('REPAIR_UNAVAILABLE', 'This session cannot open a candidate write root.', 'Repair is not available here.');
+    const { source, entry, live } = await this.#configured(plugin);
+    this.#fresh(session, plugin, live, [...reproduced.values()]);
+    let candidate;
+    try { candidate = await openCandidate({ cwd: this.cwd, stateDir: this.#state, entry }); }
+    catch (error) { throw refusal('REPAIR_OPEN_FAILED', `The candidate could not be opened: ${error.message}`, 'Report the reason; the plugin was not changed.', { workbench_code: error.code ?? null }); }
+    const drop = () => discardCandidate(candidate, { cwd: this.cwd, stateDir: this.#state }).catch(() => {});
+    // The copy must be the code that is serving: a plugin whose files changed since it loaded is not.
+    if (candidate.base.fingerprint !== live.code_fingerprint) { await drop(); throw refusal('REPAIR_BASE_MOVED', `The files of plugin ${plugin} changed since it was loaded; the copy would not be the live plugin.`, `Reload the plugin (/plugins reload ${plugin}) and reproduce the case again.`); }
+    let root;
+    try { root = (await this.policy.addCandidateRoot(candidate.tree, { container: path.join(this.#state, 'plugin-candidates') })).path; }
+    catch (error) { await drop(); throw refusal('REPAIR_OPEN_FAILED', `The candidate tree could not be opened for writing: ${error.message}`, 'Report the reason; the plugin was not changed.'); }
+    const state = { plugin, candidateId: candidate.candidateId, seal: candidate.seal, pluginsHash: source.hash, liveFingerprint: live.code_fingerprint, liveModule: live.module, root, dir: candidate.dir, tree: candidate.tree, entry: path.relative(candidate.tree, candidate.module) };
+    session.open.set(candidate.candidateId, state);
+    // A discard released the findings; a new candidate holds them again until it is accepted or discarded.
+    const recorder = this.#recorder();
+    for (const item of reproduced.values()) for (const id of item.findings) recorder?.hold?.(id);
+    const files = Object.keys(candidate.base.files).sort(), hostModules = Object.keys(candidate.host_modules ?? {}).length;
+    await this.#row({ type: 'plugin_repair_opened', plugin, candidate: candidate.candidateId, seal: candidate.seal, plugins_json_sha256: source.hash, live_fingerprint: live.code_fingerprint, base_module: candidate.base.module, entry: state.entry, files, host_modules: hostModules, write_root: root }, options);
+    return { candidate: candidate.candidateId, directory: root, module: path.join(root, state.entry), files, host_modules: hostModules,
+      note: hostModules ? `Only the plugin's own files (listed in files, under ${path.dirname(path.join(root, state.entry))}) can be repaired. The other ${hostModules} file(s) it imports are host modules: links to the installed files, shared with the house. They cannot be edited, replaced or added to here.` : 'Every file of this plugin is its own; there are no host modules.',
+      cases_to_add: [...reproduced.values()].map(item => item.case),
+      next_action: `Fix the plugin inside ${root} only, and add every case in cases_to_add to the plugin definition's cases unchanged. Then run PluginRepairTest, and PluginRepairAccept when it passes.` };
+  }
+
+  // A reproduced case is evidence about the generation it failed on. Cases from a generation that is no
+  // longer live are forgotten (their findings released) and the repair is refused until reproduced again.
+  #fresh(session, plugin, live, items) {
+    const stale = items.filter(item => item.fingerprint !== live.code_fingerprint);
+    if (!stale.length) return;
+    const recorder = this.#recorder(), known = session.reproduced.get(plugin);
+    for (const item of stale) { if (known?.get(item.digest) === item) known.delete(item.digest); for (const id of item.findings) recorder?.release?.(id); }
+    if (known && !known.size) session.reproduced.delete(plugin);
+    throw refusal('REPAIR_REPRODUCTION_STALE', `The broken promise of plugin ${plugin} was reproduced on code that is no longer live (${stale.map(item => item.case.name).join(', ')}).`, 'Reproduce the case again on the live plugin with PluginRepairReproduce.');
+  }
+
+  /**
+   * Offer the repair operations while at least one configured local plugin is repairable (enabled in
+   * plugins.json and active or failed in this session, not a builtin), and withdraw them when none is.
+   */
+  async sync(registry) {
+    let repairable = false;
+    try {
+      const enabled = new Set((await readPluginConfig(this.runtime.file, { missing: true })).entries.filter(item => item.enabled !== false).map(item => item.id));
+      repairable = this.runtime.status().plugins.some(item => !item.builtin && enabled.has(item.id) && ['active', 'failed'].includes(item.state));
+    } catch {}
+    const definitions = this.operations();
+    if (repairable) { for (const definition of definitions) if (!registry.get(definition.name)) registry.add(definition); return true; }
+    const present = definitions.map(item => item.name).filter(name => registry.get(name));
+    if (present.length) registry.replace(present, []);
+    return false;
+  }
+
+  async #discardOpen(session, state, reason, options) {
+    this.policy?.removeCandidateRoot?.(state.root); session.open.delete(state.candidateId);
+    await discardCandidate({ id: state.plugin, candidateId: state.candidateId, dir: state.dir }, { cwd: this.cwd, stateDir: this.#state }).catch(() => {});
+    const recorder = this.#recorder();
+    for (const item of session.reproduced.get(state.plugin)?.values() ?? []) for (const id of item.findings) recorder?.release?.(id);
+    await this.#row({ type: 'plugin_repair_discarded', plugin: state.plugin, candidate: state.candidateId, reason }, options).catch(() => {});
+  }
+
+  /**
+   * /new, /resume and the end of the process: open candidates of the session are discarded. One whose
+   * Accept is running is waited for (at most waitMs); if it is still running, it is discarded when it ends.
+   */
+  async endSession(sessionId, { reason = 'session_end', waitMs = 10000 } = {}) {
+    const session = this.#sessions.get(sessionId); if (!session) return 0;
+    let count = 0;
+    for (const state of [...session.open.values()]) {
+      const running = this.#running.get(state.plugin);
+      if (running) { let timer; await Promise.race([running.catch(() => {}), new Promise(resolve => { timer = setTimeout(resolve, waitMs); })]); clearTimeout(timer); }
+      if (!session.open.has(state.candidateId)) continue;   // the Accept took it
+      if (this.#busy.has(state.plugin)) { state.discardOnEnd = reason; continue; }
+      await this.#discardOpen(session, state, reason); count++;
+    }
+    return count;
+  }
+
+  async #readCandidate(state) {
+    try { return await readCandidate({ cwd: this.cwd, stateDir: this.#state, id: state.plugin, candidateId: state.candidateId, seal: state.seal }); }
+    catch (error) { throw refusal('REPAIR_CANDIDATE_REFUSED', `The candidate was refused: ${error.message}`, 'Discard this candidate and open a new one.', { workbench_code: error.code ?? null }); }
+  }
+
+  // Advice for the model: the candidate's own account, with each case evaluated by the house on the
+  // output the candidate reported. PluginRepairAccept never reads any of it.
+  async test({ candidate: candidateId }, options) {
+    const session = this.#caller(options); this.#writes(options);
+    const state = this.#candidate(session, candidateId), candidate = await this.#readCandidate(state);
+    const { entry, contract: live } = await this.#configured(state.plugin);
+    const run = this.runner ?? runCandidate, prefix = `plugin__${state.plugin}__`;
+    // A replay performs the operation for real, so it is judged like the live operation it replaces.
+    const judge = async ({ operation, input }) => { try { await this.binding.judge(operation, input, { signal: options?.signal }); return true; } catch { return false; } };
+    // The cases are the candidate's: known only once it has activated, so a first run lists them.
+    // The run is the operation's: an interrupted turn aborts it and its process group is killed.
+    // The child has no house: the house's own services are stood in by their data (see the runner).
+    const standIns = hostServiceStandIns(this.runtime), base = { config: entry.config, services: standIns.services, serviceFunctions: standIns.functions, timeoutMs: this.timeoutMs, signal: options?.signal };
+    const first = await run(candidate, base);
+    const listed = first.outcome === 'loaded' ? first.cases : [];
+    // A case runs for real wherever it runs, and Accept runs every case on the published plugin. One whose
+    // operation writes outside (effects.external 'write', as the live plugin or the candidate declares it)
+    // is left to Accept, so its effect happens once.
+    const short = name => name.startsWith(prefix) ? name.slice(prefix.length) : name;
+    const liveEffects = new Map(live.surface.operations.map(op => [op.name, op.effects])), candidateEffects = new Map((first.operations ?? []).map(op => [short(op.name), op.effects]));
+    const external = item => [liveEffects.get(item.operation), candidateEffects.get(item.operation)].some(effects => effects?.external === 'write');
+    const runnable = listed.filter(item => !external(item));
+    const report = first.outcome === 'loaded' && runnable.length ? await run(candidate, { ...base, judge, replay: runnable.map(item => ({ operation: item.operation, input: item.input, want_output: true })) }) : first;
+    const cases = listed.map(item => {
+      if (external(item)) return { name: item.name, skipped: 'external effects' };
+      const replay = report === first ? undefined : report.replays[runnable.indexOf(item)];
+      // A case that needs the house itself says nothing about the candidate here.
+      if (replay?.outcome === 'threw' && replay.code === 'PLUGIN_PREFLIGHT_UNAVAILABLE') return { name: item.name, skipped: 'house service not available in the pre-flight' };
+      let verdict;
+      if (!replay) verdict = { pass: false, reason: `Not run: the candidate run ended ${report.outcome}.` };
+      else if (replay.outcome === 'returned' && replay.output === undefined) verdict = { pass: false, reason: `The candidate did not report the output (${replay.output_omitted ?? 'not_reported'}).` };
+      else verdict = evaluateCase(item, replay.outcome === 'returned' ? { status: 'returned', output: replay.output } : replay.outcome === 'threw' ? { status: 'threw', code: replay.code, message: replay.error } : { status: 'not_run', reason: replay.outcome === 'not_permitted' ? 'the house did not permit the operation' : String(replay.outcome) });
+      return { name: item.name, pass: verdict.pass, ...(verdict.reason ? { reason: verdict.reason } : {}) };
+    });
+    let diff = null;
+    try { const full = await candidateDiff(candidate); diff = { changed: full.changed, added: full.added, removed: full.removed, host_modules: full.host_modules, review_complete: full.review_complete, unreviewed: full.unreviewed, fingerprint: full.fingerprint }; }
+    catch (error) { diff = { error: error.message, code: error.code ?? null }; }
+    // What the candidate reports covers only its operations' name, description, schemas, effects and
+    // audience and its cases; the rest of the live surface is assumed unchanged here, never at accept.
+    let contract = null;
+    if (first.outcome === 'loaded') {
+      const was = new Map(live.surface.operations.map(op => [op.name, op]));
+      const operations = report.operations.map(op => { const name = op.name.startsWith(prefix) ? op.name.slice(prefix.length) : op.name; const base = was.get(name) ?? {}; return { ...base, name, description: op.description, input_schema: op.input_schema, output_schema: op.output_schema ?? null, effects: op.effects ?? base.effects ?? null, audience: op.audience }; });
+      contract = { ...compareContracts(live, { surface: { ...live.surface, operations }, cases: listed.map(item => ({ name: item.name, digest: caseDigest(item) })) }), reported_by: 'candidate', covers: ['operations', 'cases'] };
+    }
+    const missing = [...(session.reproduced.get(state.plugin)?.values() ?? [])].filter(item => !listed.some(c => caseDigest(c) === item.digest)).map(item => item.case.name);
+    await this.#row({ type: 'plugin_repair_tested', plugin: state.plugin, candidate: candidateId, outcome: report.outcome, trust: report.trust, fingerprint: report.fingerprint ?? null, cases: cases.map(({ name, pass, skipped }) => skipped ? { name, skipped } : { name, pass }), contract_kept: contract?.kept ?? null, reproduced_missing: missing, ...(report.unavailable_services?.length ? { unavailable_services: report.unavailable_services } : {}) }, options);
+    const skipped = cases.filter(item => item.skipped).length;
+    return { outcome: report.outcome, trust: report.trust, ...(report.error ? { error: report.error } : {}), ...(report.code ? { code: report.code } : {}), ...(report.unavailable_services?.length ? { unavailable_services: report.unavailable_services } : {}), stderr_tail: report.stderr_tail, cases, diff, contract,
+      ...(missing.length ? { reproduced_cases_missing: missing } : {}), checks: report.checks, dynamic: report.dynamic, packages: report.packages ?? [],
+      next_action: report.outcome === 'aborted' ? 'The pre-flight was interrupted; nothing was learned about the candidate.'
+        : report.outcome === 'not_judged' ? `The pre-flight cannot judge this candidate: activating it needs ${(report.unavailable_services ?? []).join(', ') || 'a service'}, which the separate process does not have. Nothing was learned about the candidate here, and nothing is wrong with it for that. Accept with PluginRepairAccept {"candidate":"${candidateId}"}: the house loads it in this session, verifies the contract and runs every case itself, and restores the previous plugin if any of that fails.`
+        : report.outcome !== 'loaded' ? 'The candidate did not load in the separate process; fix it before accepting.' : missing.length ? 'Add the reproduced cases to the candidate\'s cases unchanged.' : cases.every(item => item.pass || item.skipped) ? `${skipped ? `${skipped} case(s) were skipped here (see cases): one with external effects is run once, for real, by Accept, and one that needs the house cannot run in a separate process. ` : ''}${report.dynamic?.length || report.packages?.length ? 'The changed files hold code the house cannot follow by reading it (see dynamic and packages): Accept will need an act signed by the human unless you remove it. ' : ''}This is the candidate's own account. Accept with PluginRepairAccept {"candidate":"${candidateId}"}: the house checks the contract and runs the cases itself.` : 'Some cases fail in the candidate; fix them before accepting.' };
+  }
+
+  // The overlay at <stateDir>/plugin-overlays/<id>/<fingerprint>: exactly the own files verification hashed,
+  // copied; exactly the candidate's host modules, linked to the installed files (never copied, so the
+  // repaired plugin shares the host's module instances); what open placed beside the candidate's tree
+  // (package.json, the node_modules link); and the patch. Built or found from an earlier repair, it is
+  // verified whole before it is used (verifyPlacement): anything else in it, or anything missing, refuses.
+  async #overlay(state, candidate, verified, patch) {
+    const mismatch = message => refusal('REPAIR_COPY_MISMATCH', `The overlay copy is not the verified candidate: ${message}`, 'Discard this candidate and open a new one.');
+    const root = path.join(this.#state, 'plugin-overlays'), home = path.join(root, state.plugin);
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    for (const dir of [root, home]) { const info = await lstat(dir); if (info.isSymbolicLink() || !info.isDirectory()) throw mismatch(`${dir} is not a plain directory`); }
+    const final = path.join(home, verified.fingerprint), entry = state.entry.split(path.sep), hostModules = candidate.host_modules ?? {};
+    const place = dir => ({ dir, tree: path.join(dir, 'tree'), module: path.join(dir, 'tree', ...entry), host_modules: hostModules, node_modules: candidate.node_modules ?? null, package_json: candidate.package_json });
+    const same = async dir => {
+      try { await verifyPlacement(place(dir), { files: verified.files, fingerprint: verified.fingerprint }); }
+      catch (error) { throw mismatch(error.message); }
+      // The identity trust is recorded for: the inspector's own reading, which hashes host modules at their real paths.
+      return inspectPluginModule(place(dir).module);
+    };
+    let present = null;
+    try { present = await lstat(final); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (present) {
+      // The same code was accepted before: reuse it only when it is, whole, what was verified now.
+      if (present.isSymbolicLink() || !present.isDirectory()) throw mismatch(`${final} is not a plain directory`);
+      let code;
+      try { code = await same(final); }
+      catch (error) { throw error.code === 'REPAIR_COPY_MISMATCH' ? error : mismatch(error.message); }
+      // The patch kept beside it is this repair's, so it matches the accepted row's patch_sha256.
+      await writeAtomic(path.join(final, 'repair.patch'), patch);
+      return { dir: final, code, created: false };
+    }
+    const incoming = path.join(home, `.incoming-${randomUUID()}`);
+    try {
+      await mkdir(path.join(incoming, 'tree'), { recursive: true, mode: 0o700 });
+      for (const [relative, hash] of Object.entries(verified.files).sort(([a], [b]) => a < b ? -1 : 1)) {
+        const source = path.join(candidate.tree, ...relative.split('/')), info = await lstat(source);
+        if (!info.isFile()) throw mismatch(`${relative} is no longer a regular file`);
+        const bytes = await readFile(source);
+        if (sha256(bytes) !== hash) throw mismatch(`${relative} changed after verification`);
+        const target = path.join(incoming, 'tree', ...relative.split('/'));
+        await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+        await writeFile(target, bytes, { mode: 0o600, flag: 'wx' });
+      }
+      for (const [relative, host] of Object.entries(hostModules).sort(([a], [b]) => a < b ? -1 : 1)) {
+        const link = path.join(incoming, 'tree', ...relative.split('/'));
+        await mkdir(path.dirname(link), { recursive: true, mode: 0o700 });
+        await symlink(host.target, link, 'file');
+      }
+      const packageJson = await readFile(path.join(candidate.dir, 'package.json'));
+      if (sha256(packageJson) !== candidate.package_json) throw mismatch('package.json beside the tree changed');
+      await writeFile(path.join(incoming, 'package.json'), packageJson, { mode: 0o600, flag: 'wx' });
+      if (candidate.node_modules) await symlink(candidate.node_modules, path.join(incoming, 'node_modules'), 'dir');
+      await writeFile(path.join(incoming, 'repair.patch'), patch, { mode: 0o600, flag: 'wx' });
+      await same(incoming);
+      await rename(incoming, final);
+      return { dir: final, code: await same(final), created: true };
+    } catch (error) {
+      await rm(incoming, { recursive: true, force: true }).catch(() => {});
+      throw error.code === 'REPAIR_COPY_MISMATCH' ? error : mismatch(error.message);
+    }
+  }
+
+  async accept({ candidate: candidateId, reason }, options) {
+    const session = this.#caller(options); this.#writes(options);
+    const state = this.#candidate(session, candidateId);
+    if (this.#busy.has(state.plugin)) throw refusal('REPAIR_BUSY', `A repair of plugin ${state.plugin} is already being accepted.`, 'Wait for it to finish.');
+    this.#busy.add(state.plugin);
+    const running = this.#accept(session, state, reason, options);
+    this.#running.set(state.plugin, running);
+    try { return await running; }
+    finally {
+      this.#busy.delete(state.plugin); this.#running.delete(state.plugin);
+      // The session ended while this ran: the candidate goes now, unless the Accept already took it.
+      if (state.discardOnEnd && session.open.has(state.candidateId)) await this.#discardOpen(session, state, state.discardOnEnd);
+    }
+  }
+
+  // Whether the generation serving `id` is exactly the overlay's code (the runtime committed it).
+  #serving(id, code) {
+    const item = this.runtime.status().plugins.find(plugin => plugin.id === id);
+    return item?.state === 'active' && item.module === code.module && item.code_fingerprint === code.code_fingerprint;
+  }
+
+  async #accept(session, state, reason, options) {
+    const { plugin } = state, project = this.runtime.file, prefix = `plugin__${plugin}__`, marker = pendingMarker(this.#state, plugin), token = randomUUID();
+    await this.#markerFree(plugin, options);
+    // 1. What is reviewed is what loads: the sealed metadata, then containment, then the patch.
+    const candidate = await this.#readCandidate(state);
+    let verified, diff;
+    try { verified = await verifyCandidate(candidate); diff = await candidateDiff(candidate); }
+    catch (error) { throw refusal('REPAIR_CANDIDATE_REFUSED', `The candidate was refused: ${error.message}`, 'Fix what the reason names inside the candidate tree, or discard it.', { workbench_code: error.code ?? null }); }
+    // What is reviewed is what loads only as far as the house can follow the code by reading it. A changed or
+    // added file with a construct static inspection cannot follow (a computed import(), require, eval…), or
+    // that imports a package the base did not import, may load code outside the fingerprint that anyone can
+    // change later: such a repair is never accepted on the contract alone; it needs the human's act.
+    const unfollowed = [...verified.dynamic.map(item => ({ file: item.file, construct: item.construct })), ...(verified.packages ?? []).map(item => ({ file: item.file, construct: `package ${item.specifier}` }))].slice(0, 200);
+    // 2. The base is the one the candidate was opened on, and the reproduced cases failed on it.
+    const { entry, live } = await this.#configured(plugin);
+    const moved = () => refusal('REPAIR_BASE_MOVED', `plugins.json or the live plugin ${plugin} changed since the candidate was opened.`, 'Discard this candidate, reproduce the case again and open a new one.');
+    const previousBytes = await readFile(project);
+    if (sha256(previousBytes) !== state.pluginsHash || live.code_fingerprint !== state.liveFingerprint) throw moved();
+    // A candidate that is the live code, file for file, repairs nothing: no overlay, no publish, no trust.
+    if (verified.fingerprint === (candidate.base.logical ?? candidate.base.fingerprint)) throw refusal('REPAIR_NO_CHANGE', `The candidate of plugin ${plugin} is identical to the live code.`, 'Change the plugin inside the candidate tree (fix the code and add the reproduced case), then accept again.');
+    // Only the cases known now are this repair's; one reproduced while it runs stays for later.
+    const reproduced = [...(session.reproduced.get(plugin)?.values() ?? [])];
+    this.#fresh(session, plugin, live, reproduced);
+    // 3. The overlay: a copy of the verified bytes, never the candidate tree itself.
+    const overlay = await this.#overlay(state, candidate, verified, diff.patch);
+    const dropOverlay = async () => { if (overlay.created) await rm(overlay.dir, { recursive: true, force: true }).catch(() => {}); };
+    const nextEntry = { ...entry, module: overlay.code.module };
+    const expect = { module: overlay.code.module, code_fingerprint: overlay.code.code_fingerprint };
+    // 4. A pending marker first (a crash from here on is undone at the next start), then plugins.json.
+    //    No trust is recorded for this code until the house has run its cases (step 8).
+    const raw = JSON.parse(previousBytes.toString('utf8')), index = raw.plugins.findIndex(item => item?.id === plugin);
+    // repaired_from always names the human's original: a repair of a repair keeps it, so a revert goes back there.
+    const originalRaw = raw.plugins[index].repaired_from ?? raw.plugins[index].module, originalModule = path.resolve(path.dirname(project), originalRaw);
+    raw.plugins[index] = { ...raw.plugins[index], module: overlay.code.module, repaired_from: originalRaw };
+    let written = sha256(JSON.stringify(raw, null, 2) + '\n');
+    // A repair never grants more standing than the code it replaces had. Its trust is recorded only on top of
+    // a record for exactly that code (module, fingerprint and configuration: the predicate of codeTrusted in
+    // plugin-controls.mjs; a contract_repair record for the previous overlay passes it, so repairs chain). A
+    // plugin serving only by --trust-plugins or a session-only enable has none, and its repair gets none.
+    const recorded = this.trustStore?.find?.(project, plugin);
+    const priorTrust = recorded && recorded.module === live.module && recorded.code_fingerprint === live.code_fingerprint && recorded.config_sha256 === configDigest(entry.config) ? recorded : null;
+    const pending = { version: 1, plugin, candidate: state.candidateId, token, plugins_file: project, previous_bytes: previousBytes.toString('base64'), previous_sha256: sha256(previousBytes), overlay: overlay.dir, overlay_fingerprint: overlay.code.code_fingerprint,
+      previous_trust: priorTrust, session: options?.sessionId ?? null, owner: processIdentity, at: new Date().toISOString() };
+    // The marker is this Accept's while it holds this token and this process's identity: only then is it
+    // rewritten or removed, so a marker another process created is never touched.
+    const ownsMarker = async () => { try { const now = JSON.parse(await readFile(marker, 'utf8')); return now?.token === token && sameOwner(now.owner, processIdentity); } catch { return false; } };
+    const updateMarker = async extra => { if (await ownsMarker()) await writeAtomic(marker, JSON.stringify({ ...pending, written_sha256: written, ...extra })); };
+    const removeMarker = async () => { if (await ownsMarker()) await rm(marker, { force: true }).catch(() => {}); };
+    try {
+      await mkdir(path.dirname(marker), { recursive: true, mode: 0o700 });
+      const holder = await lstat(path.dirname(marker));
+      if (holder.isSymbolicLink() || !holder.isDirectory()) throw new Error(`${path.dirname(marker)} is not a plain directory`);
+      let handle;
+      // Created exclusively: two processes can never both hold the plugin.
+      try { handle = await openFile(marker, 'wx', 0o600); }
+      catch (error) { if (error.code === 'EEXIST') throw refusal('REPAIR_BUSY_ELSEWHERE', `Another Comal process is accepting a repair of plugin ${plugin}.`, 'Wait for it to finish, then reproduce the case again: the plugin may already be repaired.', { overlay_left: overlay.created }); throw error; }
+      try { await handle.writeFile(JSON.stringify({ ...pending, written_sha256: written })); await handle.sync(); } finally { await handle.close(); }
+      if (sha256(await readFile(project)) !== state.pluginsHash) throw moved();
+      const checked = await writePluginConfigRaw(project, raw);
+      if (checked.hash !== written) { written = checked.hash; await updateMarker(); }
+    } catch (error) {
+      let current = null; try { current = await readFile(project); } catch {}
+      const mine = await ownsMarker();
+      if (mine && current && sha256(current) === written) await writeAtomic(project, previousBytes, 0o644).catch(() => {});
+      await removeMarker();
+      // Lost the race for the marker: the other Accept may be using this very overlay (the same fix), so it stays.
+      if (error.code !== 'REPAIR_BUSY_ELSEWHERE') await dropOverlay();
+      throw error.code?.startsWith?.('REPAIR_') ? error : refusal('REPAIR_LOAD_FAILED', `plugins.json could not be prepared: ${error.message}`, 'Report the reason; nothing was changed.');
+    }
+
+    // 5. Prepare, admit by contract, publish.
+    let admission = { kind: 'none' }, trust = { recorded: false }, previousTrust;
+    const files = [...diff.changed, ...diff.added, ...diff.removed];
+    const admit = async (staged, { staged: activation, retiring }) => {
+      // A repair publishes exactly its plugin and retires only its previous generation.
+      if (activation.some(item => item.id !== plugin) || retiring.some(id => id !== plugin)) { admission = { kind: 'scope', staged: activation.map(item => item.id), retiring: [...retiring] }; return false; }
+      // A staged contract that cannot be stated (malformed cases, a surface that is not plain JSON) loads, but
+      // there is nothing to compare or to show the human: it is never admitted as a repair.
+      if (staged?.invalid) { admission = { kind: 'contract_invalid', reason: String(staged.invalid).slice(0, 2000) }; return false; }
+      const before = this.runtime.contract(plugin), comparison = compareContracts(before, staged);
+      const digests = new Set(staged.cases.map(item => item.digest)), missing = reproduced.filter(item => !digests.has(item.digest)).map(item => item.case.name);
+      if (missing.length) { admission = { kind: 'case_missing', missing, comparison }; return false; }
+      const contracts = { before: summary(before), after: summary(staged) };
+      if (comparison.kept && !unfollowed.length) { admission = { kind: 'kept', comparison, ...contracts }; return true; }
+      // An act answers exactly one change, from this contract to that one, once; when it covers code the house
+      // cannot follow, it answers exactly this code.
+      const code = unfollowed.length ? verified.fingerprint : null;
+      const signed = session.acts.find(act => !act.consumed && act.plugin === plugin && sameContract(act.before, contracts.before) && sameContract(act.after, contracts.after) && (act.code ?? null) === code);
+      if (signed) { signed.consumed = true; admission = { kind: 'act', act: signed.row, comparison, unfollowed, ...contracts }; return true; }
+      if (typeof this.confirm !== 'function') { admission = { kind: 'needs_act', human: 'absent', comparison, unfollowed, ...contracts }; return false; }
+      let card = actCard({ plugin, comparison, reason, files, before, after: staged, unfollowed });
+      if (card.truncated) {
+        // The full contracts beside the overlay, named on the card.
+        const saved = { before: path.join(overlay.dir, 'contract-before.json'), after: path.join(overlay.dir, 'contract-after.json') };
+        try { await writeAtomic(saved.before, JSON.stringify(before, null, 2)); await writeAtomic(saved.after, JSON.stringify(staged, null, 2)); card = actCard({ plugin, comparison, reason, files, before, after: staged, saved, unfollowed }); } catch {}
+      }
+      let yes = false;
+      try { yes = (await this.confirm('PluginContractAct', { plugin, surface_changed: comparison.surface_changed, cases_removed: comparison.cases_removed, cases_changed: comparison.cases_changed, cases_added: comparison.cases_added, unfollowed, reason: reason ?? null, files, before: contracts.before, after: contracts.after }, { summary: card.text })) === true; }
+      catch { yes = false; }
+      if (!yes) { admission = { kind: 'needs_act', human: 'declined', comparison, unfollowed, ...contracts }; return false; }
+      // The act is sealed before the generation is admitted; it stays in the journal whatever follows. Its
+      // record for the human's view (/plugins acts) is written first and removed if the row cannot be sealed,
+      // so the view never shows an act the journal does not hold, nor misses one it does.
+      const act = { type: 'plugin_contract_act', plugin, candidate: state.candidateId, before: contracts.before, after: contracts.after, surface_changed: comparison.surface_changed, cases_removed: comparison.cases_removed, cases_changed: comparison.cases_changed, cases_added: comparison.cases_added, unfollowed, ...(code ? { code_fingerprint: code } : {}), reason: reason ?? null, files, signed_by: 'human', signed_at: new Date().toISOString() };
+      const actFile = path.join(actsDir(this.#state), plugin, `${act.signed_at.replace(/[:.]/g, '-')}-${randomUUID()}.json`);
+      const actRecord = { version: 1, plugin, candidate: state.candidateId, session: options?.sessionId ?? null, signed_at: act.signed_at, signed_by: 'human', reason: act.reason, surface_changed: act.surface_changed, cases_removed: act.cases_removed, cases_changed: act.cases_changed, cases_added: act.cases_added, unfollowed, before: act.before, after: act.after };
+      try { await mkdir(path.dirname(actFile), { recursive: true, mode: 0o700 }); await writeAtomic(actFile, JSON.stringify({ ...actRecord, act: null }, null, 2) + '\n'); }
+      catch (error) { admission = { kind: 'needs_act', human: 'signed_unrecorded', error: error.message, comparison, unfollowed, ...contracts }; return false; }
+      let row;
+      try { row = await this.#row(act, options); }
+      catch (error) { await rm(actFile, { force: true }).catch(() => {}); admission = { kind: 'needs_act', human: 'signed_unrecorded', error: error.message, comparison, unfollowed, ...contracts }; return false; }
+      await writeAtomic(actFile, JSON.stringify({ ...actRecord, act: ref(row) }, null, 2) + '\n').catch(() => {});
+      session.acts.push({ plugin, before: contracts.before, after: contracts.after, code, row: ref(row), consumed: true });
+      admission = { kind: 'act', act: ref(row), comparison, unfollowed, ...contracts }; return true;
+    };
+    const previous = { module: live.module, code_fingerprint: live.code_fingerprint };
+    let cleanupError = null;
+    // The record of this repair for the human's view (repair.json beside repair.patch), written in step 8.
+    // A rollback after it puts back what was there (a reused overlay's earlier record) or removes it.
+    const recordFile = path.join(overlay.dir, REPAIR_RECORD);
+    let recordWritten = false, recordPrevious = null;
+    // Undo: plugins.json only if it is still what this repair wrote (never someone else's edit), trust if
+    // it was recorded, the previous generation if the repaired one was published, the overlay unless an
+    // edit still names it, and the marker once plugins.json is settled.
+    const rollback = async ({ published, stage, code, why, failing }) => {
+      const restored = { plugins_json: false, trust: true, generation: published ? 'reloaded' : 'kept' };
+      let current = null; try { current = await readFile(project); } catch {}
+      if (current && sha256(current) === written) { try { await writeAtomic(project, previousBytes, 0o644); restored.plugins_json = true; } catch (error) { restored.plugins_json_error = error.message; } }
+      else if (current && sha256(current) === sha256(previousBytes)) restored.plugins_json = true;
+      else restored.plugins_json = 'left_as_edited';
+      if (trust.recorded) { try { await this.trustStore.restore(project, plugin, previousTrust); } catch (error) { restored.trust = false; restored.trust_error = error.message; } }
+      if (published) {
+        // Not the turn's signal: an interrupted turn must still get its previous plugin back.
+        try { await this.runtime.load(plugin, { expect: previous }); }
+        catch (error) { restored.generation_error = error.message; try { await this.runtime.disable(plugin); restored.generation = 'disabled'; } catch (disable) { restored.generation = 'failed'; restored.disable_error = disable.message; } }
+      } else { try { await this.runtime.discover(); } catch {} }
+      if (recordWritten) { try { if (recordPrevious) await writeAtomic(recordFile, recordPrevious); else await rm(recordFile, { force: true }); } catch (error) { restored.record_error = error.message; } }
+      if (restored.plugins_json === 'left_as_edited' && current?.toString('utf8').includes(JSON.stringify(overlay.code.module).slice(1, -1))) restored.overlay = 'kept_referenced';
+      else await dropOverlay();
+      if (restored.plugins_json === true || restored.plugins_json === 'left_as_edited') await removeMarker();
+      else restored.pending_marker = 'kept';
+      await this.#row({ type: 'plugin_repair_rolled_back', plugin, candidate: state.candidateId, stage, code, reason: String(why).slice(0, 2000), ...(failing ? { failing_case: failing } : {}), ...(admission.act ? { act: admission.act } : {}), ...(admission.comparison ? { comparison: admission.comparison } : {}), ...(admission.unfollowed?.length ? { unfollowed: admission.unfollowed } : {}), ...(cleanupError ? { cleanup_error: cleanupError } : {}), restored }, options).catch(() => null);
+      return restored;
+    };
+    const settled = restored => restored.plugins_json === 'left_as_edited' ? 'plugins.json was edited by someone else meanwhile and was left as edited; the repaired code is not trusted.' : '';
+    try { await this.runtime.load(plugin, { expect, admit, signal: options?.signal }); }
+    catch (error) {
+      // A failure after the commit (the previous generation's cleanup) leaves the repaired code serving:
+      // that is a publish, and its cases decide. Anything else published nothing.
+      if (error?.code !== 'PLUGIN_NOT_ADMITTED' && this.#serving(plugin, overlay.code)) cleanupError = [error?.message ?? String(error), ...(Array.isArray(error?.errors) ? error.errors.map(item => item?.message ?? String(item)) : [])].join(': ').slice(0, 2000);
+      else {
+        const refusedBy = error?.code === 'PLUGIN_NOT_ADMITTED' ? admission.kind : null;
+        const code = { needs_act: 'REPAIR_NEEDS_ACT', case_missing: 'REPAIR_CASE_MISSING', scope: 'REPAIR_SCOPE', contract_invalid: 'REPAIR_CONTRACT_INVALID' }[refusedBy] ?? 'REPAIR_LOAD_FAILED';
+        const cannotFollow = code === 'REPAIR_NEEDS_ACT' && admission.comparison?.kept;
+        const why = cannotFollow ? `The repair of plugin ${plugin} holds code the house cannot follow by reading it (${admission.unfollowed.map(item => `${item.file}: ${item.construct}`).join(', ')}); it needs an act signed by the human (${admission.human}).`
+          : code === 'REPAIR_NEEDS_ACT' ? `The repair changes the contract of plugin ${plugin}; it needs an act signed by the human (${admission.human}).`
+          : code === 'REPAIR_CASE_MISSING' ? `The candidate does not carry the reproduced case(s): ${admission.missing.join(', ')}.`
+          : code === 'REPAIR_SCOPE' ? `Accepting would also publish or retire other plugins (staged: ${admission.staged.join(', ')}; retiring: ${admission.retiring.join(', ')}).`
+          : code === 'REPAIR_CONTRACT_INVALID' ? `The contract of the candidate cannot be stated (${admission.reason}), so the house cannot tell whether it keeps the live one.`
+          : `The repaired plugin did not load: ${error.message}`;
+        const restored = await rollback({ published: false, stage: refusedBy ? 'admit' : 'load', code, why });
+        const next = cannotFollow ? (admission.human === 'absent' ? 'No human is present to sign. Write the fix with literal relative imports of the plugin\'s own files and the packages it already imports (no computed import(), require, createRequire, eval or new Function, no new packages), or ask the human to accept it in an interactive session.' : 'The human did not sign. Write the fix without those constructs, or explain why they are needed and try again.')
+          : code === 'REPAIR_NEEDS_ACT' ? (admission.human === 'absent' ? 'No human is present to sign. Keep the contract (same operations and schemas, every existing case unchanged; only add cases), or ask the human to accept the change in an interactive session.' : 'The human did not sign the change. Keep the contract, or explain the change and try again.')
+          : code === 'REPAIR_CASE_MISSING' ? 'Add each reproduced case to the plugin definition\'s cases exactly as reproduced, then accept again.'
+          : code === 'REPAIR_SCOPE' ? 'Repair one plugin at a time; a repair cannot change its providers or consumers.'
+          : code === 'REPAIR_CONTRACT_INVALID' ? 'Fix the candidate\'s cases ({ name, operation, input, expect }, each naming one of its operations) and keep its schemas plain JSON, then accept again.'
+          : 'Fix the candidate (PluginRepairTest shows import and activation errors) and accept again.';
+        throw refusal(code, `${why} ${settled(restored) || 'Nothing was changed.'}`, next, { ...(admission.comparison ? { surface_changed: admission.comparison.surface_changed, cases_removed: admission.comparison.cases_removed, cases_changed: admission.comparison.cases_changed, cases_added: admission.comparison.cases_added } : {}), ...(admission.unfollowed?.length ? { unfollowed: admission.unfollowed } : {}), ...(admission.missing ? { missing: admission.missing } : {}), restored });
+      }
+    }
+    // The repaired generation serves from here on: every way out below either keeps it verified or rolls it back.
+    const undo = async (code, why, next, extra = {}) => {
+      const restored = await rollback({ published: true, stage: extra.stage ?? 'cases', code, why, failing: extra.failing });
+      const after = restored.generation === 'reloaded' ? 'The previous plugin was restored.' : restored.generation === 'disabled' ? 'The previous plugin could not be loaded again, so the plugin was disabled.' : 'The previous plugin could not be restored; ask the human to check /plugins.';
+      // A rollback puts the plugin back; it does not undo what the cases that ran did. Their bounded outputs go
+      // with the refusal (in its details, shown to the model; never in the journal), and the message says so.
+      const ran = extra.cases?.length ? ' The cases that ran before the rollback ran for real: a case whose operation has effects performed them, and what they left behind is yours. Their outputs are in cases; use them to clean up.' : '';
+      return refusal(code, `${why}. ${after} ${settled(restored)}`.trim() + ran, next, { ...(extra.failing ? { failing_case: extra.failing } : {}), ...(extra.cases?.length ? { cases: extra.cases } : {}), restored });
+    };
+    // 6. Every case of the published contract, run by the house through the normal permission path.
+    const published = this.runtime.contract(plugin), results = [], shown = [], budget = { left: CASE_OUTPUT_TOTAL };
+    let failing = null;
+    if (options?.invocation_id) this.#standing.set(plugin, { invocation: options.invocation_id, module: overlay.code.module, code_fingerprint: overlay.code.code_fingerprint, config_sha256: configDigest(entry.config), previous: { module: live.module, code_fingerprint: live.code_fingerprint } });
+    try {
+      for (const item of published?.cases ?? []) {
+        const result = await this.#call(`${prefix}${item.operation}`, item.input, options);
+        const outcome = result.status === 'not_run' ? { pass: false, reason: `Not run: ${result.reason}` } : evaluateCase(item, result);
+        results.push({ name: item.name, digest: item.digest, pass: outcome.pass, status: result.status, ...(outcome.reason ? { reason: outcome.reason } : {}), receipt: result.receipt });
+        shown.push({ name: item.name, pass: outcome.pass, ...caseShown(result, budget) });
+        if (!outcome.pass) { failing = results.at(-1); break; }
+      }
+    } catch (error) { failing = { name: '(interrupted)', pass: false, status: 'not_run', reason: `The case runs were interrupted: ${error?.message ?? error}`, receipt: null }; }
+    finally { this.#standing.delete(plugin); }
+    if (!published || failing) {
+      // 7. The house restores the previous generation by itself; the finding stays open.
+      const why = failing ? `Case "${failing.name}" ${failing.status === 'not_run' ? 'could not be run' : 'failed'} on the published plugin: ${failing.reason}` : 'The published plugin has no contract';
+      throw await undo('REPAIR_ROLLED_BACK', why, failing?.status === 'not_run' ? 'The house must be able to run every case; a case it cannot run (permission, plan mode) does not prove the repair.' : 'Fix the candidate so every case passes in this process, then accept again.', { failing, cases: shown });
+    }
+    // 8. Verified: only now is the new code trusted, and the repair stands only once its row is sealed. The
+    //    journal must never claim a repair plugins.json does not hold: it is checked again on each side.
+    const holds = async () => { try { return sha256(await readFile(project)) === written; } catch { return false; } };
+    const elsewhere = 'plugins.json changed while the house verified the repair';
+    if (!await holds()) throw await undo('REPAIR_BASE_MOVED', elsewhere, 'Look at plugins.json; reproduce the case again on the live plugin if it still fails.', { stage: 'record' });
+    previousTrust = priorTrust ?? undefined;
+    if (!priorTrust) trust = { recorded: false, reason: 'no_prior_trust' };
+    else try { await this.trustStore.trust({ project, entry: nextEntry, code: overlay.code, reason: 'contract_repair' }); trust = { recorded: true }; }
+    catch (error) {
+      // With --trust-plugins the session needs no remembered trust; it is recorded when it can be.
+      if (!this.trustByFlag) throw await undo('REPAIR_TRUST_FAILED', `Trust for the repaired code could not be recorded: ${error.message}`, 'Report the reason.', { stage: 'trust' });
+      trust = { recorded: false, error: String(error.message).slice(0, 300) };
+    }
+    const authority = admission.kind === 'act' ? 'signed_act' : 'contract_kept';
+    if (!await holds()) throw await undo('REPAIR_BASE_MOVED', elsewhere, 'Look at plugins.json; reproduce the case again on the live plugin if it still fails.', { stage: 'record' });
+    // The human's view of this repair, beside its patch. Informational: the accepted row below is the authority.
+    try {
+      try { recordPrevious = await readFile(recordFile); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      recordWritten = true;
+      await writeAtomic(recordFile, JSON.stringify({ version: 1, plugin, accepted_at: new Date().toISOString(), session: options?.sessionId ?? null, candidate: state.candidateId, authority,
+        fingerprint_before: live.code_fingerprint, fingerprint_after: verified.fingerprint, contract_before: admission.before, contract_after: admission.after,
+        cases: results.map(item => item.name), patch_sha256: sha256(diff.patch), overlay: overlay.code.module, before_module: live.module, original_module: originalModule, act: admission.act ?? null, trust }, null, 2) + '\n');
+    } catch (error) {
+      throw await undo('REPAIR_NOT_RECORDED', `The record of the accepted repair could not be written: ${error.message}`, 'Report the reason; an unrecorded repair does not stand.', { stage: 'record' });
+    }
+    let accepted;
+    try {
+      accepted = await this.#row({ type: 'plugin_repair_accepted', plugin, candidate: state.candidateId, fingerprint_before: live.code_fingerprint, fingerprint_after: verified.fingerprint,
+        contract_before: admission.before, contract_after: admission.after, authority, ...(admission.act ? { act: admission.act } : {}),
+        cases: results.map(({ name, digest, pass, receipt }) => ({ name, digest, pass, receipt })), patch_sha256: sha256(diff.patch), overlay: overlay.code.module, repaired_from: live.module, original_module: originalModule,
+        overlay_fingerprint: overlay.code.code_fingerprint, host_modules: verified.host_modules,
+        dynamic: verified.dynamic, packages: verified.packages ?? [], unreviewed: diff.unreviewed, review_complete: diff.review_complete, trust, ...(cleanupError ? { cleanup_error: cleanupError } : {}), ...(reason ? { reason: String(reason).slice(0, 2000) } : {}) }, options);
+    } catch (error) {
+      throw await undo('REPAIR_NOT_RECORDED', `The accepted repair could not be sealed in the journal: ${error.message}`, 'Report the reason; an unrecorded repair does not stand.', { stage: 'record' });
+    }
+    // Sealed: a crash from here on must not undo it. The marker says so before it goes.
+    await updateMarker({ completed: true }).catch(() => {});
+    await removeMarker();
+    const recorder = this.#recorder(), proof = { receipts: results.filter(item => item.receipt).map(item => ({ case: item.name, ...item.receipt })), ...(ref(accepted) ? { accepted: ref(accepted) } : {}) };
+    const known = session.reproduced.get(plugin);
+    for (const item of reproduced) {
+      for (const id of item.findings) await recorder?.resolve?.(id, { state: 'repaired_in_run', proof });
+      // A case reproduced again while this ran keeps its newer findings.
+      const current = known?.get(item.digest);
+      if (current) { current.findings = current.findings.filter(id => !item.findings.includes(id)); if (current === item || !current.findings.length) known.delete(item.digest); }
+    }
+    if (known && !known.size) session.reproduced.delete(plugin);
+    this.policy?.removeCandidateRoot?.(state.root);
+    session.open.delete(state.candidateId);
+    await discardCandidate(candidate, { cwd: this.cwd, stateDir: this.#state }).catch(() => {});
+    // A work step that failed on the promise this repair fixed is fenced as uncertain; the accepted repair
+    // releases it, and only it. The repair stands whether or not the release could be recorded.
+    let released = [];
+    if (typeof this.releaseFence === 'function' && ref(accepted)) { try { released = await this.releaseFence({ plugin, accepted: ref(accepted), sessionId: options?.sessionId, invocation_id: options?.invocation_id }) ?? []; } catch { released = []; } }
+    const again = released.length ? ` The house released the fence this failure left on your work plan: ${released.map(item => `task ${item.task_id}, step ${item.step_id} (${item.operation})`).join('; ')}. Run that step again with WorkStepRun and the SAME step_id; other work in the task is no longer fenced by it. The house cannot know whether the failed call had an outside effect before it threw.` : '';
+    return { accepted: true, fingerprint: verified.fingerprint, authority, cases: shown, overlay: overlay.code.module, ...(released.length ? { released_steps: released } : {}),
+      next_action: `Plugin ${plugin} is repaired in this session; call its operations again to continue your task.${again} The cases ran for real on the published plugin: a case whose operation has effects performed them, and what they left behind is yours. Each case's output (or what it threw) is in cases; use those values to continue or to clean up.` };
+  }
+
+  async discard({ candidate: candidateId }, options) {
+    const session = this.#caller(options), state = this.#candidate(session, candidateId);
+    if (this.#busy.has(state.plugin)) throw refusal('REPAIR_BUSY', `A repair of plugin ${state.plugin} is being accepted.`, 'Wait for it to finish.');
+    // Closed for writing first, then removed by the workbench's own checks.
+    this.policy?.removeCandidateRoot?.(state.root);
+    session.open.delete(candidateId);
+    try { await discardCandidate({ id: state.plugin, candidateId, dir: state.dir }, { cwd: this.cwd, stateDir: this.#state }); }
+    catch (error) { throw refusal('REPAIR_DISCARD_FAILED', `The candidate directory could not be removed: ${error.message}`, 'It is closed for writing; report the reason.', { workbench_code: error.code ?? null }); }
+    // The broken promise is still broken: its finding is released and closes as open, unless a later repair takes it.
+    const recorder = this.#recorder();
+    for (const item of session.reproduced.get(state.plugin)?.values() ?? []) for (const id of item.findings) recorder?.release?.(id);
+    await this.#row({ type: 'plugin_repair_discarded', plugin: state.plugin, candidate: candidateId, reason: 'requested' }, options);
+    return { discarded: true, next_action: 'The candidate is gone. Open a new one with PluginRepairOpen to try again; the reproduced case is remembered for this session.' };
+  }
+
+  operations() {
+    const caseSchema = { type: 'object', properties: { name: { type: 'string', minLength: 1, maxLength: 120 }, operation: { type: 'string', pattern: '^[A-Za-z][A-Za-z0-9_]{0,31}$' }, input: { type: 'object' }, expect: { type: 'object' } }, required: ['name', 'operation', 'input', 'expect'], additionalProperties: false };
+    // Each repair invocation is adopted by the recorder: its refusals and its nested case calls are answers, not friction.
+    // Under Reproduce, a refused call is friction the human caused (a permission No, plan mode): kept as a finding.
+    const definition = (name, description, properties, required, run, children) => ({ name, description, input_schema: { type: 'object', properties, required, additionalProperties: false }, surfaces: ['agent'], steps: true,
+      run: (input, options) => { try { this.#recorder()?.adopt?.(options?.invocation_id, children ? { children } : undefined); } catch {} return run(input, options); } });
+    return [
+      definition('PluginRepairReproduce', 'Reproduce a broken promise of a local plugin: state it as a case { name, operation, input, expect } where expect is { returns: value the output must contain } | { output_schema: schema } | { throws: { code } }. The house calls the live operation through the normal permission path and evaluates the case itself. A failing case is recorded as a contract_mismatch finding and becomes the case the repair must add.', { plugin: ID, case: caseSchema }, ['plugin', 'case'], (input, options) => this.reproduce(input, options), row => row.status !== 'refused'),
+      definition('PluginRepairOpen', 'Open a candidate copy of a local plugin to repair a promise reproduced in this session. Returns the candidate id and the only directory you may write: fix the code there and add the reproduced case to the plugin\'s cases. Only the plugin\'s own files (the directory of its entry module) are copied and can be changed; the other modules it imports are host modules, linked to the installed files and shared with the house. The installed plugin and its original files are never written.', { plugin: ID }, ['plugin'], (input, options) => this.open(input, options)),
+      definition('PluginRepairTest', 'Pre-flight an open candidate in a separate process: it is loaded, its cases are replayed (each judged like the live operation) and evaluated by the house, and you get its diff and how its reported contract compares with the live one. The process has no house: the house\'s own services are stood in by their data, a case whose operation declares external writes is skipped (Accept runs it once, for real), and a candidate that needs another plugin\'s service to activate is not_judged. This is the candidate\'s own account, for you; acceptance does not rely on it.', { candidate: UUID }, ['candidate'], (input, options) => this.test(input, options)),
+      definition('PluginRepairAccept', 'Ask the house to accept an open candidate. The house verifies it, copies it to an overlay, stages it in this session and compares the staged contract with the live one: if the surface is the same, every existing case is unchanged and the reproduced cases are present, it publishes it, runs every case through the normal permission path and keeps it only if all pass; otherwise it restores the previous plugin by itself. A change of contract needs an act signed by the human (REPAIR_NEEDS_ACT when there is none), and so does changed code the house cannot follow by reading it: a computed import(), require, createRequire, eval, new Function, or a package the plugin did not import before. Give your reason for the change.', { candidate: UUID, reason: { type: 'string', maxLength: 2000 } }, ['candidate'], (input, options) => this.accept(input, options)),
+      definition('PluginRepairDiscard', 'Discard an open candidate: its directory and write root are removed and the plugin stays as it is; the broken promise stays recorded as an open finding.', { candidate: UUID }, ['candidate'], (input, options) => this.discard(input, options)),
+    ];
+  }
+}
+