@milpa/comal 0.2.6 → 0.2.8

package/src/house.mjs

@@ -17,6 +17,12 @@ const savedBroadAllow = (rules, name) => !rules?.decide?.(name, {})?.list?.match
 });
 
 
+// Refusals whose source is the human's own No to a permission question; the receipt says so.
+const humanRefusals = new WeakSet();
+// The first receipt that recorded an error object, and the invocation it would propagate to next. Only that
+// direct parent, rethrowing it in the same book, says so (relayed_from); an unrelated later throw does not.
+const receiptedErrors = new WeakMap();
+
 // Textos de la tarjeta de confirmación: sólo los ve el humano.
 registerMessages({
   'Could not verify the summary': 'No se pudo verificar el resumen',
@@ -54,7 +60,9 @@ export class House {
   #scopeMechanisms = new Map();
   #revokedScopes = new Set();
   constructor({ cwd, registry = new OperationRegistry(), record }) { this.cwd = cwd; this.registry = registry; this.hasRecorder = Boolean(record); this.record = record || (async () => {}); }
-  snapshot(rows) { return houseSnapshot(rows, { active: this.#active, exclude: this.#context.getStore()?.id }); }
+  // The host may attach the finding recorder's swallowed count: () => number.
+  findingsUnrecorded = null;
+  snapshot(rows) { return houseSnapshot(rows, { active: this.#active, exclude: this.#context.getStore()?.id, findingsUnrecorded: this.findingsUnrecorded?.() }); }
   stateContext() { return { active: new Set(this.#active), exclude: this.#context.getStore()?.id }; }
   recoveryAdapter(sessionId,name) {return this.#recoveries.get(`${sessionId}:${name}`);}
   registerRecovery(sessionId,name,handler) {const key=`${sessionId}:${name}`;this.#recoveries.set(key,handler);return ()=>{if(this.#recoveries.get(key)===handler)this.#recoveries.delete(key);};}
@@ -292,7 +300,7 @@ export class House {
     const active = this.#context.getStore();
     await this.emit(context, { type: 'house_decision', invocation_id: active?.id ?? null, contract_digest: active?.contractDigest ?? null, operation: name, arguments_digest: digest(input), allowed: Boolean(decision.allowed), reason: decision.reason, mode: context.policy.mode, ...(['permission_rule', 'confirm_always'].includes(decision.source) ? { permission_source: decision.source, ...(typeof decision.rule === 'string' ? { rule: decision.rule } : {}) } : {}) });
     if (active) active.decisions.push(Boolean(decision.allowed));
-    if (!decision.allowed) { throw hostRefusalFailure(`Permission denied: ${name}: ${decision.reason}`, 'HOUSE_REFUSED', 'permission', {type:'house_decision'}); }
+    if (!decision.allowed) { const error = hostRefusalFailure(`Permission denied: ${name}: ${decision.reason}`, 'HOUSE_REFUSED', 'permission', {type:'house_decision'}); if (decision.refused_by === 'human') humanRefusals.add(error); throw error; }
     signal?.throwIfAborted(); return decision;
   }
   async execute(context, catalog, name, input, { signal, callId, work, beforeEffect, modelProposed = false, modelSurface } = {}) {
@@ -395,8 +403,11 @@ export class House {
       });
     } catch (error) {
       const refusalCause=settleNativeRefusal(error,{...base,house:this.cwd,session_id:context.sessionId});
-      await this.emit(context, { type: 'house_receipt', ...base, ...(refusalCause?{refusal_cause:refusalCause}:{}), status: entered ? 'failed' : 'refused', disposition: ['HOUSE_STALE', 'HOUSE_POSTCONDITION', 'HOUSE_AUTHORITY_CHANGED', 'HOUSE_SURFACE_CHANGED'].includes(error.code) ? 'repeat' : 'basket', judgment_scope: 'house_execution', code: error.code, error: error.message, effects_observed: entered ? 'unknown_or_partial' : 'none', observations: state.observations, asked: 'unjudged', ...(state.confirmCard ? { confirm_card: state.confirmCard } : {}) });
+      const keyed = error !== null && (typeof error === 'object' || typeof error === 'function'), first = keyed ? receiptedErrors.get(error) : undefined;
+      const relayedFrom = first && first.session_id === context.sessionId && first.next === id ? first.invocation_id : undefined;
+      await this.emit(context, { type: 'house_receipt', ...base, ...(refusalCause?{refusal_cause:refusalCause}:{}), ...(humanRefusals.has(error) ? { refused_by: 'human' } : {}), ...(relayedFrom ? { relayed_from: relayedFrom } : {}), status: entered ? 'failed' : 'refused', disposition: ['HOUSE_STALE', 'HOUSE_POSTCONDITION', 'HOUSE_AUTHORITY_CHANGED', 'HOUSE_SURFACE_CHANGED'].includes(error.code) ? 'repeat' : 'basket', judgment_scope: 'house_execution', code: error.code, error: error.message, effects_observed: entered ? 'unknown_or_partial' : 'none', observations: state.observations, asked: 'unjudged', ...(state.confirmCard ? { confirm_card: state.confirmCard } : {}) });
       receiptRecorded = true;
+      if (keyed) receiptedErrors.set(error, { invocation_id: relayedFrom ?? id, session_id: context.sessionId, next: base.parent_invocation_id });
       throw error;
     } finally {
       // Host-owned resources outlive the handler and its durable outcome. A
@@ -408,7 +419,7 @@ export class House {
 }
 
 // Derive closure from executor events, never from tool JSON saying verified=true.
-export function houseSnapshot(rows, { active = new Set(), exclude } = {}) {
+export function houseSnapshot(rows, { active = new Set(), exclude, findingsUnrecorded } = {}) {
   const started = new Map(), receipts = [];
   for (const row of rows) {
     if (row.invocation_id === exclude && exclude) continue;
@@ -418,5 +429,5 @@ export function houseSnapshot(rows, { active = new Set(), exclude } = {}) {
   const counts = Object.fromEntries(['returned', 'failed', 'refused'].map(status => [status, receipts.filter(r => r.status === status).length]));
   const permissionRefusals = rows.filter(row => row.type === 'house_decision' && !row.allowed).length;
   const unresolved = [...started.keys()].filter(id => !active.has(id)), running = [...started.keys()].filter(id => active.has(id));
-  return { scope: 'house_execution', asked: 'unjudged', status: unresolved.length ? 'interrupted' : running.length ? 'running' : counts.failed || counts.refused || permissionRefusals ? 'needs_review' : receipts.length ? 'recorded' : 'no_receipts', counts, permission_refusals: permissionRefusals, unresolved, running, receipts: receipts.slice(-40).map(({ output, ...row }) => row), receipt_total: receipts.length, integrity: 'local_journal_not_signed' };
+  return { scope: 'house_execution', asked: 'unjudged', status: unresolved.length ? 'interrupted' : running.length ? 'running' : counts.failed || counts.refused || permissionRefusals ? 'needs_review' : receipts.length ? 'recorded' : 'no_receipts', counts, permission_refusals: permissionRefusals, unresolved, running, receipts: receipts.slice(-40).map(({ output, ...row }) => row), receipt_total: receipts.length, ...(Number.isInteger(findingsUnrecorded) && findingsUnrecorded > 0 ? { findings_unrecorded: findingsUnrecorded } : {}), integrity: 'local_journal_not_signed' };
 }

package/src/i18n/cli-es.mjs

@@ -1,6 +1,6 @@
 // Original host messages for the optional Spanish interface. No user/model content.
 export default Object.freeze({
-  "\nFrom inside a session (no flags needed):\n  /config [set KEY VALUE|save] · /max-tokens [N] · /context-window [auto|N] · /raw\n  /login PROVIDER [--key|--api-key-env VARIABLE] (hidden key field; ollama = Ollama Cloud)\n  /plugins available|add ID [k=v…]|config ID [k=v…]|remove ID|trust|untrust ID|allow ID observe|all|none|OP…\n  /chrome-workflow [auto|raw] · /autonomy [observe|assist|edit|autonomous]\n  /permissions [MODE|allow|ask|deny|remove RULE [--sesion|--proyecto|--usuario]]\n": "\nDesde dentro de la sesión (sin banderas):\n  /config [set CLAVE VALOR|save] · /max-tokens [N] · /context-window [auto|N] · /raw\n  /login PROVEEDOR [--key|--api-key-env VARIABLE] (campo oculto para la llave; ollama = Ollama Cloud)\n  /plugins available|add ID [k=v…]|config ID [k=v…]|remove ID|trust|untrust ID|allow ID observe|all|none|OP…\n  /chrome-workflow [auto|raw] · /autonomy [observar|asistir|editar|autonomo]\n  /permissions [MODO|allow|ask|deny|remove REGLA [--sesion|--proyecto|--usuario]]\n",
+  "\nFrom inside a session (no flags needed):\n  /config [set KEY VALUE|save] · /max-tokens [N] · /context-window [auto|N] · /raw\n  /login PROVIDER [--key|--api-key-env VARIABLE] (hidden key field; ollama = Ollama Cloud)\n  /plugins available|add ID [k=v…]|config ID [k=v…]|remove ID|trust|untrust ID|allow ID observe|all|none|OP…|repairs|acts|revert ID\n  /chrome-workflow [auto|raw] · /autonomy [observe|assist|edit|autonomous]\n  /permissions [MODE|allow|ask|deny|remove RULE [--sesion|--proyecto|--usuario]]\n": "\nDesde dentro de la sesión (sin banderas):\n  /config [set CLAVE VALOR|save] · /max-tokens [N] · /context-window [auto|N] · /raw\n  /login PROVEEDOR [--key|--api-key-env VARIABLE] (campo oculto para la llave; ollama = Ollama Cloud)\n  /plugins available|add ID [k=v…]|config ID [k=v…]|remove ID|trust|untrust ID|allow ID observe|all|none|OP…|repairs|acts|revert ID\n  /chrome-workflow [auto|raw] · /autonomy [observar|asistir|editar|autonomo]\n  /permissions [MODO|allow|ask|deny|remove REGLA [--sesion|--proyecto|--usuario]]\n",
   "Permission bypass is fixed for this process. Restart Comal without --dangerously-skip-permissions to change modes.": "El bypass de permisos queda fijo en este proceso. Reinicia Comal sin --dangerously-skip-permissions para cambiar de modo.",
   "Permission bypass active: prompts and classifier skipped for this process.": "Bypass de permisos activo: este proceso omite confirmaciones y clasificador.",
   "\n  --dangerously-skip-permissions  Skip permission prompts/classifier for this process; startup only. Explicit denials and operation contracts still apply.\n": "\n  --dangerously-skip-permissions  Omite confirmaciones y clasificador en este proceso; sólo al arrancar. Se conservan denegaciones explícitas y contratos.\n",

package/src/i18n/es.mjs

@@ -160,6 +160,8 @@ export default Object.freeze({
   "vision": "visión",
   "connecting": "conectando",
   "Enlarge the terminal to 24×10": "Amplía el terminal a 24×10",
+  "Permission: {v0}": "Permiso: {v0}",
+  "Waiting for your answer": "Esperando tu respuesta",
   "  {v0} interrupted message(s); not resent. R requeues the first.": "  {v0} mensaje(s) interrumpidos; no se reenviaron. R reencola el primero.",
   "  Empty queue. Send a message while the agent works.": "  Cola vacía. Envía un mensaje mientras el agente trabaja.",
   "  Running: ": "  En ejecución: ",
@@ -482,6 +484,26 @@ export default Object.freeze({
   "{run} run · {blocked} blocked · {done} done": "{run} en curso · {blocked} bloq. · {done} hechas",
   "{q} questions · {p} plans": "{q} preguntas · {p} planes",
   "/swarm opens": "/swarm lo abre",
-  "Comal is working · Esc to see the conversation": "Comal está trabajando · Esc para ver la conversación"
+  "Comal is working · Esc to see the conversation": "Comal está trabajando · Esc para ver la conversación",
+  "Plugin {plugin}: the repair changes what it promises. Sign only if you accept the new contract.": "Plugin {plugin}: la reparación cambia lo que promete. Firma sólo si aceptas el contrato nuevo.",
+  "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 {plugin}: la reparación mantiene lo que promete, pero contiene código que la casa no puede seguir leyéndolo. Firma sólo si revisaste ese código.",
+  "Code the house cannot follow: {list}": "Código que la casa no puede seguir: {list}",
+  "Surface changed: {list}": "Superficie cambiada: {list}",
+  "Cases removed: {list}": "Casos eliminados: {list}",
+  "Cases changed: {list}": "Casos cambiados: {list}",
+  "Cases added: {list}": "Casos añadidos: {list}",
+  "The model's reason: {reason}": "Motivo del modelo: {reason}",
+  "Files in the patch: {list}": "Archivos del parche: {list}",
+  "Yes signs the act and the repaired plugin is published and checked; No (the default) leaves everything as it is.": "Sí firma el acta y el plugin reparado se publica y se comprueba; No (la opción por defecto) deja todo como está.",
+  "(none)": "(ninguno)",
+  "(none given)": "(no dio ninguno)",
+  "before: {value}": "antes: {value}",
+  "after: {value}": "después: {value}",
+  "{count} item(s) truncated; the full contracts before and after are in {before} and {after}.": "{count} elemento(s) recortado(s); los contratos completos de antes y después están en {before} y {after}.",
+  "An interrupted plugin repair could not be recovered ({error}); its marker was left in place and plugins.json was not changed. Review it with /plugins.": "No se pudo recuperar una reparación de plugin interrumpida ({error}); su marcador se dejó en su sitio y plugins.json no se cambió. Revísalo con /plugins.",
+  "The working directory {cwd} is inside a private Comal location ({location}). File tools (Read, Write, Edit, Grep…) are refused here: Comal keeps its configuration, credentials and session state out of the model's reach. Start Comal in your project directory, or choose another --state-dir.": "El directorio de trabajo {cwd} está dentro de una ubicación privada de Comal ({location}). Las herramientas de archivos (Read, Write, Edit, Grep…) se rechazan aquí: Comal mantiene su configuración, credenciales y estado de sesión fuera del alcance del modelo. Inicia Comal en el directorio de tu proyecto, o elige otro --state-dir.",
+  "A plugin repair was interrupted before it was verified; plugins.json was put back as it was before it.": "Una reparación de plugin se interrumpió antes de verificarse; plugins.json volvió a como estaba antes.",
+  "An unreadable plugin repair marker was removed; plugins.json was not changed.": "Se eliminó una marca ilegible de reparación de plugin; plugins.json no cambió.",
+  "A plugin repair was interrupted, but plugins.json was edited since; it was left as it is. Review it with /plugins.": "Una reparación de plugin se interrumpió, pero plugins.json se editó después; se dejó como está. Revísalo con /plugins."
 
 });

package/src/operations.mjs

@@ -8,12 +8,22 @@ export const digest = value => createHash('sha256').update(JSON.stringify(canoni
 export const immutable = value => { if (value && typeof value === 'object' && !Object.isFrozen(value)) { Object.values(value).forEach(immutable); Object.freeze(value); } return value; };
 const validatorOptions = { strict: false, allErrors: true, validateFormats: false };
 
+// Repair by contract (plugin-repair.mjs): offered to the root agent only, never to a subagent's surface.
+export const PLUGIN_REPAIR_OPERATION_NAMES = Object.freeze(['PluginRepairReproduce', 'PluginRepairOpen', 'PluginRepairTest', 'PluginRepairAccept', 'PluginRepairDiscard']);
+
 // An effect ceiling describes declared reach, never proof of actual remote effects.
 export function toolEffects(name) {
   if (['ListDirectory', 'FileInfo'].includes(name)) return { workspace: 'read', external: 'none', process: 'none', authority: 'none' };
   if (['Read', 'Glob', 'Grep', 'McpStatus', 'HouseContext', 'HouseSnapshot', 'OperationCatalog', 'ReadTable', 'PluginStatus', 'WorkSnapshot', 'AuditStatus', 'EvidenceRead'].includes(name)) return { workspace: 'read', external: 'none', process: 'none', authority: 'none' };
   if (['Write', 'Edit'].includes(name)) return { workspace: 'write', external: 'none', process: 'none', authority: 'none' };
   if (['WebSearch', 'WebFetch'].includes(name)) return { workspace: 'none', external: 'read', process: 'none', authority: 'none' };
+  // Repair by contract (plugin-repair.mjs). Reproduce calls a plugin operation, whose own effects are not
+  // known statically; Test runs candidate code in a child process; Accept writes plugins.json and the trust
+  // record and loads code in this process; Open and Discard create or remove the candidate's write root.
+  if (name === 'PluginRepairReproduce') return { workspace: 'unknown', external: 'unknown', process: 'unknown', authority: 'none' };
+  if (name === 'PluginRepairOpen' || name === 'PluginRepairDiscard') return { workspace: 'write', external: 'none', process: 'none', authority: 'candidate_write_root' };
+  if (name === 'PluginRepairTest') return { workspace: 'unknown', external: 'unknown', process: 'spawn', authority: 'none' };
+  if (name === 'PluginRepairAccept') return { workspace: 'write', external: 'unknown', process: 'unknown', authority: 'plugin_lifecycle' };
   return { workspace: 'unknown', external: 'unknown', process: 'unknown', authority: 'none' };
 }
 

package/src/permission-rules.mjs

@@ -268,11 +268,12 @@ export class PermissionRules {
     return ruleCovers(parsed, name, input, { list, project: this.project || process.cwd(), groups: this.groups });
   }
   /** Precedencia: deny > ask > allow. Devuelve la regla decisiva o undefined. */
-  decide(name, input) {
+  // context: { invocation } of the call being judged, passed to gate (it never changes deny or ask).
+  decide(name, input, context) {
     const found = this.applicable().filter(rule => this.matches(rule, name, input));
     const deny = found.find(rule => rule.list === 'deny'); if (deny) return deny;
     const ask = found.find(rule => rule.list === 'ask'); if (ask) return ask;
-    return found.find(rule => rule.list === 'allow' && this.gate(name));
+    return found.find(rule => rule.list === 'allow' && this.gate(name, context));
   }
   /** Reemplaza las reglas que cumplen `remove` por `add`, en una sola escritura atómica. */
   async update({ remove = () => false, add = [] } = {}) {

package/src/permissions.mjs

@@ -7,9 +7,18 @@ import { readOnlyBashCheck, chromeLabObservation, openRelayObservation, omarchyO
 import { describeRule, suggestRule } from './permission-rules.mjs';
 import { measureHumanWait } from './turn-timing.mjs';
 import { realpath, stat } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+// The same, synchronously, for the policy's construction.
+function canonicalishSync(file) {
+  let ancestor = path.resolve(file), suffix = [];
+  while (true) {
+    try { return path.join(realpathSync(ancestor), ...suffix); }
+    catch { const parent = path.dirname(ancestor); if (parent === ancestor) return path.resolve(file); suffix.unshift(path.basename(ancestor)); ancestor = parent; }
+  }
+}
 const within = (root, file) => { const relative = path.relative(root, file); return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)); };
 
 /** realpath of the nearest existing ancestor plus the rest: a location not created yet still compares canonically. */
@@ -114,15 +123,22 @@ function normalizeAnswer(value, offer) {
   return { allowed: Boolean(value), remember: null };
 }
 const CONFIRM_ALWAYS = 'confirm:"always"';
+const humanRefusal = answer => answer.refused_by === 'human' ? { refused_by: 'human' } : {};
 
 export class PermissionPolicy {
   #mode;
   // rules: almacén de reglas guardadas (permission-rules.mjs) con decide(name, input) → {list, rule, scope}.
   // contractOf(name): contrato vivo de la operación (house.registry.get(name)?.contract); de ahí sale
   // el techo duro confirm:'always', que sólo el host lee y el modelo no puede cambiar.
-  #workRoots = []; #private = []; #privateExtra;
-  constructor({ mode = 'default', dangerouslySkipPermissions = false, allowed = [], denied = [], confirm, classifier, cwd, rules, contractOf, onDecision = () => {}, readRoots = [], privateLocations: privateExtra = [] } = {}) {
+  #workRoots = []; #private = []; #privateExtra; #candidateRoots = []; #ownWorkspace = null;
+  constructor({ mode = 'default', dangerouslySkipPermissions = false, allowed = [], denied = [], confirm, classifier, cwd, rules, contractOf, onDecision = () => {}, readRoots = [], privateLocations: privateExtra = [], ownWorkspace } = {}) {
     this.#privateExtra = [...privateExtra];
+    // Host-only (scoped-policy.mjs): the workspace the house created for a child inside one of the extra private
+    // locations (an owned Git worktree under the --state-dir). That tree, and only it, is not private for this
+    // policy; the rest of the location still is. Comal's standard private locations are never exempted.
+    if (typeof ownWorkspace === 'string' && ownWorkspace) this.#ownWorkspace = { root: canonicalishSync(ownWorkspace), locations: this.#privateExtra.flatMap(location => [path.resolve(location), canonicalishSync(location)]) };
+    // Private from the start, for every path the tools resolve (the --state-dir included, wherever it is).
+    for (const location of privateLocations({ extra: this.#privateExtra })) this.#private.push(location, canonicalishSync(location));
     if (!PERMISSION_MODES.includes(mode) && !(dangerouslySkipPermissions === true && mode === BYPASS_PERMISSION_MODE)) throw new Error('Invalid permission mode. Use default, plan, acceptEdits or auto; bypass requires the startup flag.');
     Object.defineProperty(this, 'dangerouslySkipPermissions', { value: dangerouslySkipPermissions === true, enumerable: true });
     this.#mode = this.dangerouslySkipPermissions ? BYPASS_PERMISSION_MODE : mode;
@@ -147,9 +163,53 @@ export class PermissionPolicy {
     return { added: true, path: canonical };
   }
   /** Host-only: another session was resumed in this process; its own /add-dir rows are restored next. */
-  clearWorkRoots() { this.#workRoots = []; }
+  clearWorkRoots() { this.#workRoots = []; this.#candidateRoots = []; }
+  /**
+   * Host-only (plugin-repair.mjs): the exact tree of an open plugin candidate, `<container>/<id>/<uuid>/tree`
+   * where container is `<stateDir>/plugin-candidates`. It is the one writable place under Comal state: inside
+   * it, and only there, the .comal/.harness rule and the state directory's own privacy (--state-dir) do not
+   * apply. Any other private Comal location still refuses it. Removed with removeCandidateRoot.
+   */
+  async addCandidateRoot(dir, { container, env, home } = {}) {
+    if (typeof dir !== 'string' || typeof container !== 'string') throw new TypeError('addCandidateRoot requires the candidate tree and its container.');
+    const canonical = await realpath(dir), box = await realpath(container), info = await stat(canonical);
+    const parts = path.relative(box, canonical).split(path.sep);
+    if (!info.isDirectory() || parts.length !== 3 || parts[2] !== 'tree' || parts.some(part => !part || part === '..') || path.isAbsolute(path.relative(box, canonical))) throw new Error(`Not a plugin candidate tree: ${dir}`);
+    if (info.mode & 0o002) throw new Error(`The candidate tree is world-writable: ${canonical}`);
+    const stateDir = path.dirname(box), exempt = [];
+    for (const location of privateLocations({ env, home, extra: this.#privateExtra })) {
+      const real = await canonicalish(location);
+      if ([location, real].includes(stateDir)) { exempt.push(location, real); continue; }   // the state directory itself (--state-dir)
+      if ([location, real].some(item => within(canonical, item) || within(item, canonical))) throw new Error(`The candidate tree touches a private Comal location (${location}).`);
+    }
+    this.#private = [];
+    for (const location of privateLocations({ env, home, extra: this.#privateExtra })) this.#private.push(location, await canonicalish(location));
+    if (!this.#candidateRoots.some(entry => entry.root === canonical)) { this.#candidateRoots.push({ root: canonical, exempt }); this.#workRoots.push(canonical); }
+    return { added: true, path: canonical };
+  }
+  removeCandidateRoot(dir) {
+    const entry = this.#candidateRoots.find(item => item.root === dir); if (!entry) return false;
+    this.#candidateRoots = this.#candidateRoots.filter(item => item !== entry); this.#workRoots = this.#workRoots.filter(root => root !== entry.root); return true;
+  }
+  /** The open candidate trees (canonical paths; a frozen copy). */
+  get candidateRoots() { return Object.freeze(this.#candidateRoots.map(entry => entry.root)); }
+  /** The open candidate tree holding `file` (canonical), or null. */
+  candidateRootOf(file) { return this.#candidateRoots.find(entry => within(entry.root, file))?.root ?? null; }
+  /** The private locations given at construction (the --state-dir and the other paths named by flags): a scoped policy takes them too. */
+  get privateExtra() { return Object.freeze([...this.#privateExtra]); }
+  /** The private Comal location that holds `file` (canonical), or null. An open candidate's tree is not inside one. */
+  privateLocationOf(file) {
+    const candidate = this.#candidateRoots.find(entry => within(entry.root, file));
+    return this.#private.find(location => within(location, file) && !candidate?.exempt.includes(location) && !this.#own(location, file)) ?? null;
+  }
+  /** The workspace the house gave this policy inside a private location (see the constructor), or undefined. */
+  get ownWorkspace() { return this.#ownWorkspace?.root; }
+  #own(location, file) { return Boolean(this.#ownWorkspace) && this.#ownWorkspace.locations.includes(location) && within(this.#ownWorkspace.root, file); }
   /** A private Comal location or a path an active plugin protects: closed even under an added directory. */
-  isPrivate(file) { return this.#private.some(location => within(location, file)) || isProtectedPath(file); }
+  isPrivate(file) {
+    const candidate = this.#candidateRoots.find(entry => within(entry.root, file));
+    return this.#private.some(location => within(location, file) && !candidate?.exempt.includes(location) && !this.#own(location, file)) || isProtectedPath(file);
+  }
   get mode() { return this.#mode; }
   set mode(mode) {
     if (this.dangerouslySkipPermissions) throw new Error(BYPASS_LOCKED_MESSAGE);
@@ -179,16 +239,16 @@ export class PermissionPolicy {
     signal?.throwIfAborted();
     if (this.denied.has(name)) return { allowed: false, reason: 'Explicit denial rule' };
     // Saved human rules: deny > ask > allow. Ask forces a question even in auto; the startup bypass skips it (deny still applies).
-    const rule = this.rules?.decide(name, input), ruled = rule ? `Permission ${describeRule(rule)}` : null, cite = rule ? { rule: rule.rule } : {};
+    const rule = this.rules?.decide(name, input, { invocation }), ruled = rule ? `Permission ${describeRule(rule)}` : null, cite = rule ? { rule: rule.rule } : {};
     if (rule?.list === 'deny') return { allowed: false, reason: ruled, source: 'permission_rule', ...cite };
     if (this.mode === BYPASS_PERMISSION_MODE) return { allowed: true, reason: 'Explicit startup --dangerously-skip-permissions; permission prompts and classifier skipped', source: 'startup_bypass' };
     if (this.confirmAlways(name)) {
       if (this.mode === 'plan') return { allowed: false, reason: `Plan mode: la operación declara ${CONFIRM_ALWAYS} y plan no la ejecuta`, source: 'confirm_always' };
       if (!this.confirm) return { allowed: false, reason: `La operación declara ${CONFIRM_ALWAYS} y no hay un humano que confirme`, source: 'confirm_always' };
       const answer = await this.#question(name, input, signal, onWaiting, null); if (answer.stale) return answer;
-      return { allowed: answer.allowed, reason: `Confirmación obligatoria (${CONFIRM_ALWAYS}): ${answer.allowed ? 'User confirmation' : 'No authorization for this tool'}`, source: 'confirm_always' };
+      return { allowed: answer.allowed, reason: `Confirmación obligatoria (${CONFIRM_ALWAYS}): ${answer.allowed ? 'User confirmation' : 'No authorization for this tool'}`, source: 'confirm_always', ...humanRefusal(answer) };
     }
-    if (rule?.list === 'ask') { const answer = await this.#question(name, input, signal, onWaiting, null); if (answer.stale) return answer; return { allowed: answer.allowed, reason: `${ruled}: ${answer.allowed ? 'User confirmation' : 'No authorization for this tool'}`, source: 'permission_rule', ...cite }; }
+    if (rule?.list === 'ask') { const answer = await this.#question(name, input, signal, onWaiting, null); if (answer.stale) return answer; return { allowed: answer.allowed, reason: `${ruled}: ${answer.allowed ? 'User confirmation' : 'No authorization for this tool'}`, source: 'permission_rule', ...cite, ...humanRefusal(answer) }; }
     const granted = this.allowed.has(name) || rule?.list === 'allow';
     const knownRead = READ_TOOLS.has(name) || granted && (chromeLabObservation(name) || openRelayObservation(name) || omarchyObservation(name));
     if (name === 'Agent' || name === 'AgentBatch') return { allowed: true, reason: 'Delegation: every child action retains the session permissions' };
@@ -203,7 +263,7 @@ export class PermissionPolicy {
     const offer = this.rememberOffer(name, input), answer = await this.#question(name, input, signal, onWaiting, offer);
     if (answer.stale) return answer;
     const base = reason ?? (answer.allowed ? 'User confirmation' : 'No authorization for this tool');
-    return { allowed: answer.allowed, reason: answer.saved ? `${base}; saved ${describeRule(answer.saved)}` : answer.saveError ? `${base}; the rule was not saved: ${answer.saveError}` : base, ...(answer.saved ? { source: 'permission_rule', rule: answer.saved.rule } : {}) };
+    return { allowed: answer.allowed, reason: answer.saved ? `${base}; saved ${describeRule(answer.saved)}` : answer.saveError ? `${base}; the rule was not saved: ${answer.saveError}` : base, ...(answer.saved ? { source: 'permission_rule', rule: answer.saved.rule } : {}), ...humanRefusal(answer) };
   }
   /** Regla propuesta para «sí, siempre» o null (sin almacén, confirm:'always' o sin regla segura). */
   rememberOffer(name, input) {
@@ -219,7 +279,9 @@ export class PermissionPolicy {
     const slot=new Promise(resolve => {release=resolve;});
     const tail=previous.catch(() => {}).then(() => slot);
     confirmationQueues.set(confirm,tail);
-    const questionId=randomUUID();let allowed=false,displayed=false;
+    // Why the card closed comes back out of band (onOutcome), never in confirm's value: callers of confirm
+    // test its truthiness, so it stays a boolean (or { allowed: true, remember } when «always» was offered).
+    const questionId=randomUUID();let allowed=false,displayed=false,outcome;
     try {
       await waitWithAbort(previous,signal);
       signal?.throwIfAborted();
@@ -230,9 +292,12 @@ export class PermissionPolicy {
       await onWaiting?.({type:'house_waiting',question_id:questionId});
       displayed=true;signal?.throwIfAborted();
       // The visible card is human time: excluded from the turn's Comal time.
-      const answer=normalizeAnswer(await measureHumanWait(()=>waitWithAbort(confirm(name,input,{signal,questionId,...(offer?{remember:offer}:{})}),signal)),offer);
+      const answer=normalizeAnswer(await measureHumanWait(()=>waitWithAbort(confirm(name,input,{signal,questionId,onOutcome:why=>{outcome=why;},...(offer?{remember:offer}:{})}),signal)),offer);
       signal?.throwIfAborted();
       allowed=answer.allowed && this.confirm===confirm && (stamp===permissionStamp(this) || visible===houseStamp(this) && this.rules?.decide(name,input)?.list!=='deny');
+      // Only the human's plain No (outcome 'no') marks the refusal; edit before sending, a closed
+      // screen, an abort, an interrupt and a stale or changed authority do not.
+      if(!answer.allowed && outcome==='no')return { allowed:false, refused_by: 'human' };
       if(!allowed || !answer.remember)return { allowed };
       // Se guarda antes de liberar el turno, para que la siguiente pregunta ya la vea.
       const scope=answer.remember==='user' ? 'user' : this.rules.scope;

package/src/plugin-candidate-child.mjs

@@ -0,0 +1,204 @@
+// The child side of the plugin workbench runner (plugin-candidate-runner.mjs). It runs in
+// its own process and process group, started as
+//   node --max-old-space-size=512 plugin-candidate-child.mjs <candidate module>
+// and speaks JSON lines: requests on stdin, reports on the real stdout. Candidate code
+// writing through console.log or process.stdout.write is sent to stderr instead, so a noisy
+// plugin is not a protocol error; bytes written straight to fd 1 still reach the parent and
+// count against its protocol bound.
+//
+// Nothing here is a security boundary against the candidate: candidate code runs in this
+// same process and can write anything it likes, forged reports included. The parent treats
+// every message as untrusted, bounded data; isolation protects the session, not the truth
+// of the report.
+//
+// The recording context mirrors PluginRuntime#stage (src/plugins.mjs) and the manifest checks
+// mirror PluginRuntime#definition: both are private to PluginRuntime, so the minimum is
+// replicated here. Operations are built with the live Operation class, so schema
+// compilation and input/output validation are the live ones.
+import { pathToFileURL } from 'node:url';
+import { createInterface } from 'node:readline';
+import { writeSync } from 'node:fs';
+import { Operation, immutable, toolEffects, digest } from './operations.mjs';
+import { validateCases } from './plugin-contract.mjs';
+
+// Reports are written synchronously to fd 1, so a process.exit right after one loses nothing.
+const toStderr = process.stderr.write.bind(process.stderr);
+process.stdout.write = (chunk, encoding, callback) => toStderr(chunk, encoding, callback);
+function send(message) {
+  const bytes = Buffer.from(`${JSON.stringify(message)}\n`);
+  for (let offset = 0; offset < bytes.length;) {
+    try { offset += writeSync(1, bytes, offset); } catch (error) { if (error.code !== 'EAGAIN') throw error; }
+  }
+}
+
+const TEXT = 2000, MAX_OPERATIONS = 200, MAX_CHECKS = 200, OUTPUT_BYTES = 256 * 1024, OUTPUT_TOTAL = 2 * 1024 * 1024;
+const text = value => String(value ?? '').slice(0, TEXT);
+const errorText = error => text(error instanceof Error ? error.message : error);
+const jsonCopy = value => JSON.parse(JSON.stringify(value));
+const idPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+// operationName in plugin-catalog.mjs; not imported, since that module loads the bundled plugins.
+const published = (id, name) => name.startsWith('plugin__') ? name : `plugin__${id}__${name}`;
+const HOOK_EVENTS = ['operation:result', 'operation:decision', 'skill:started', 'skill:completed'];
+const OPERATION_KEYS = ['name', 'description', 'input_schema', 'output_schema', 'effects', 'run', 'confirm', 'confirm_summary'];
+
+// The checks of PluginRuntime#definition, and the id the candidate was opened for.
+function checkDefinition(definition, id) {
+  if (!definition || typeof definition !== 'object' || !idPattern.test(definition.id) || definition.id.length > 24 || typeof definition.version !== 'string' || !definition.version || typeof definition.activate !== 'function') throw new Error('Invalid plugin manifest: requires id, version and activate.');
+  if (definition.id !== id) throw new Error(`The module's plugin id ${definition.id} is not the candidate's id ${id}.`);
+  for (const key of ['requires', 'provides']) {
+    const list = definition[key] ?? [];
+    if (!Array.isArray(list) || list.length > 32 || list.some(name => typeof name !== 'string' || !name || name.length > 128) || new Set(list).size !== list.length) throw new Error('Invalid plugin requires/provides.');
+  }
+  if (definition.tool_loading !== undefined && !['eager', 'deferred'].includes(definition.tool_loading)) throw new Error('tool_loading must be eager or deferred.');
+  if (definition.hook_timeout_ms !== undefined && (!Number.isInteger(definition.hook_timeout_ms) || definition.hook_timeout_ms < 10 || definition.hook_timeout_ms > 5000)) throw new Error('hook_timeout_ms requires 10–5000 ms.');
+  return { requires: [...(definition.requires ?? [])], provides: [...(definition.provides ?? [])], cases: validateCases(definition.cases) };
+}
+
+// What the candidate printed to stderr is part of the report: let it drain (briefly) before leaving.
+async function leave(code) {
+  const until = performance.now() + 500;
+  while (process.stderr.writableLength > 0 && performance.now() < until) await new Promise(resolve => setTimeout(resolve, 5));
+  process.exit(code);
+}
+
+const lines = createInterface({ input: process.stdin, crlfDelay: Infinity })[Symbol.asyncIterator]();
+async function next() {
+  const { value, done } = await lines.next();
+  if (done) process.exit(0);   // the parent is gone
+  return JSON.parse(value);
+}
+
+async function main() {
+  const init = await next();
+  if (init?.type !== 'init') throw new Error('Expected init.');
+  const started = performance.now();
+  const remaining = () => Math.max(0, init.deadline_ms - (performance.now() - started));
+  const id = init.id, config = init.config ?? {};
+  // The house's own services, stood in: the plain data the parent passed, plus a function for each member
+  // that is a function in the house. Such a function exists (a plugin may look at it) and throws when it is
+  // called: this process has no house to answer it. What activation needed and could not have is told to
+  // the parent, which then says the candidate was not judged rather than that it failed.
+  const unavailable = new Set();
+  const notHere = what => Object.assign(new Error(`${what} is not available in the pre-flight: it runs in a separate process without the house. The house verifies the candidate when it is accepted.`), { code: 'PLUGIN_PREFLIGHT_UNAVAILABLE' });
+  const services = {};
+  for (const [name, value] of Object.entries(init.services ?? {})) {
+    const members = Array.isArray(init.service_functions?.[name]) ? init.service_functions[name].filter(key => typeof key === 'string') : [];
+    if (!members.length || value === null || typeof value !== 'object' || Array.isArray(value)) { services[name] = value; continue; }
+    const standIn = { ...value };
+    for (const key of members) Object.defineProperty(standIn, key, { enumerable: true, value: () => { if (staging) unavailable.add(`${name}.${key}()`); throw notHere(`${name}.${key}`); } });
+    services[name] = Object.freeze(standIn);
+  }
+
+  let module, definition, manifest;
+  try {
+    module = await import(pathToFileURL(process.argv[2]).href);
+    definition = module.default;
+    manifest = checkDefinition(definition, id);
+  } catch (error) {
+    send({ type: 'import_failed', error: errorText(error) });
+    return leave(0);
+  }
+  const missing = manifest.requires.filter(name => !Object.hasOwn(services, name));
+  send({ type: 'imported', missing_services: missing });
+
+  // The recording context: the surface of PluginRuntime#stage.
+  const controller = new AbortController();
+  const operations = new Map(), provided = new Set(), disposers = [];
+  let staging = true;
+  const declaring = () => { if (!staging) throw new Error('Capabilities are only declared during activate.'); };
+  const register = (spec, human = false) => {
+    declaring();
+    for (const key of Object.keys(spec)) if (!OPERATION_KEYS.includes(key)) throw new Error(`Contract reserved to the host: ${key}`);
+    if (Object.hasOwn(spec, 'confirm') && spec.confirm !== 'always') throw new Error("A plugin's confirm only admits 'always'.");
+    if (Object.hasOwn(spec, 'confirm_summary') && typeof spec.confirm_summary !== 'function') throw new Error("A plugin's confirm_summary must be a function.");
+    if (!/^[A-Za-z][A-Za-z0-9_]{0,31}$/.test(spec.name) || typeof spec.run !== 'function') throw new Error('Invalid plugin operation name/handler.');
+    const name = `plugin__${id}__${spec.name}`;
+    if (name.length > 64 || operations.has(name)) throw new Error(`Duplicate operation or name too long: ${name}`);
+    const handler = spec.run;
+    const operation = new Operation({ name, description: spec.description, input_schema: spec.input_schema, output_schema: spec.output_schema, effects: spec.effects || toolEffects('__unknown_plugin'), audience: human ? 'human' : 'any', surfaces: human ? ['cli', 'tui'] : ['cli', 'tui', 'agent'], permission: name, ...(spec.confirm ? { confirm: spec.confirm } : {}), run: (input, signal) => handler(immutable(jsonCopy(input)), Object.freeze({ signal })) });
+    operations.set(name, operation);
+    return name;
+  };
+  const context = Object.freeze({
+    signal: controller.signal,
+    config: immutable(jsonCopy(config)),
+    operation: spec => register(spec), command: spec => register(spec, true),
+    service: name => {
+      if (!manifest.requires.includes(name)) throw new Error(`Service not declared/available: ${name}`);
+      // Declared, and not one of the house's own: another plugin provides it, and none is loaded here.
+      if (!Object.hasOwn(services, name)) { if (staging) unavailable.add(name); throw notHere(`Service ${name}`); }
+      return services[name];
+    },
+    provide: name => { declaring(); if (!manifest.provides.includes(name) || provided.has(name)) throw new Error(`Service not declared/duplicate: ${name}`); provided.add(name); },
+    defer: disposer => { if (typeof disposer !== 'function') throw new Error('Cleanup requires a function.'); disposers.push(disposer); },
+    on: (event, listener) => { if (!HOOK_EVENTS.includes(event) || typeof listener !== 'function') throw new Error('Invalid plugin hook.'); },
+    guard: check => { declaring(); if (typeof check !== 'function') throw new Error('A guard requires a function.'); },
+    notify: async () => ({ status: 'unavailable' }),
+  });
+  const listed = () => [...operations.values()].slice(0, MAX_OPERATIONS).map(({ contract }) => ({ name: contract.name, description: text(contract.description), input_schema: contract.input_schema, output_schema: contract.output_schema, effects: contract.effects, audience: contract.audience }));
+
+  try {
+    if (definition.config_schema) new Operation({ name: `${id}_config`, description: 'Plugin configuration', input_schema: definition.config_schema, run: () => '' }).validate(config);
+    await definition.activate(context, context.config);
+    for (const name of manifest.provides) if (!provided.has(name)) throw new Error(`The plugin did not publish the declared service: ${name}`);
+    validateCases(manifest.cases, [...operations.keys()].map(name => name.slice(`plugin__${id}__`.length)));
+  } catch (error) {
+    send({ type: 'activate_failed', error: errorText(error), operations: listed(), ...(unavailable.size ? { unavailable_services: [...unavailable].slice(0, 32) } : {}) });
+    return leave(0);
+  }
+  staging = false;
+  send({ type: 'activated', operations: listed(), cases: manifest.cases });
+
+  // A handler run as the house runs it: input validated, a frozen copy in, output validated.
+  const invoke = async (name, input, budget) => {
+    const operation = operations.get(published(id, String(name)));
+    if (!operation) throw new Error(`Unknown operation: ${name}`);
+    operation.validate(input);
+    const output = await operation.run(input, AbortSignal.any([controller.signal, AbortSignal.timeout(Math.max(1, Math.floor(Number(budget) || 1)))]));
+    operation.validateOutput(output);
+    return output;
+  };
+
+  const checks = [];
+  const suite = module.checks ?? definition.checks;
+  if (suite !== undefined) {
+    if (!suite || typeof suite !== 'object' || Array.isArray(suite)) checks.push({ name: 'checks', ok: false, error: 'The checks export must be an object of functions.' });
+    else for (const [name, check] of Object.entries(suite).slice(0, MAX_CHECKS)) {
+      if (typeof check !== 'function') { checks.push({ name: text(name), ok: false, error: 'Not a function.' }); continue; }
+      try { await check((operation, input) => invoke(operation, input, remaining())); checks.push({ name: text(name), ok: true }); }
+      catch (error) { checks.push({ name: text(name), ok: false, error: errorText(error) }); }
+    }
+  }
+  send({ type: 'checks', checks });
+  send({ type: 'ready' });
+
+  let outputLeft = OUTPUT_TOTAL;   // the parent's budget for asked-for outputs, kept here too so stdout stays bounded
+  for (;;) {
+    const request = await next();
+    if (request?.type === 'replay') {
+      try {
+        const output = await invoke(request.operation, request.input, request.remaining_ms);
+        let rendered;
+        try { rendered = typeof output === 'string' ? output : JSON.stringify(output) ?? '(no output)'; }
+        catch { throw new Error('The output is not JSON-serializable.'); }
+        let asked = {};
+        if (request.want_output === true) {
+          const bytes = Buffer.byteLength(JSON.stringify(rendered));
+          asked = bytes > OUTPUT_BYTES ? { output_omitted: 'too_large' } : bytes > outputLeft ? { output_omitted: 'budget' } : (outputLeft -= bytes, { output: rendered });
+        }
+        send({ type: 'replayed', seq: request.seq, outcome: 'returned', output_sha256: digest(rendered), ...asked });
+      } catch (error) {
+        send({ type: 'replayed', seq: request.seq, outcome: 'threw', error: errorText(error), ...(typeof error?.code === 'string' ? { code: error.code.slice(0, 128) } : {}) });
+      }
+    } else if (request?.type === 'done') {
+      // Retire as the runtime does: abort the scope, then run the cleanups in reverse.
+      controller.abort(new Error('Plugin retired.'));
+      const errors = [];
+      for (const disposer of disposers.reverse()) try { await disposer(); } catch (error) { errors.push(errorText(error)); }
+      send({ type: 'closed', cleanup: errors.length ? { ok: false, error: text(errors.join('; ')) } : { ok: true } });
+      return leave(0);
+    } else throw new Error('Unexpected request.');
+  }
+}
+
+main().catch(error => { toStderr(`plugin-candidate-child: ${errorText(error)}\n`); process.exit(70); });