@milpa/comal 0.2.7 → 0.2.8

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); });