@milpa/comal 0.2.1 → 0.2.2

package/src/plugins/open-relay/actions.mjs

@@ -2,6 +2,8 @@ import { createHash } from 'node:crypto';
 import { digest } from '../../operations.mjs';
 import { clean, excerpt } from './bound.mjs';
 import { messageOrNull, messageOfDelivery, taskForMessage, pendingDelivery, planOrNull } from './lookup.mjs';
+import { METHOD_CAPS } from './client.mjs';
+import { decisionBlock, chosenOption, adrScope, draftAdr, adrDigest } from './decision.mjs';
 import { t, registerMessages } from '../../i18n/index.mjs';
 
 // Fase 2: cuatro acciones sobre el enjambre. Cada una lleva una tarjeta de
@@ -30,7 +32,38 @@ registerMessages({
   'Confirm delivery (msg.ack): {v0}': 'Confirmar la entrega (msg.ack): {v0}',
   'yes, the message is marked read': 'sí, el mensaje queda leído',
   'no': 'no',
-  'Decision note (only in the Comal receipt; phase 3 will store it as an ADR):': 'Nota de decisión (sólo en el recibo de Comal; la fase 3 la guardará como ADR):',
+  'Decision note (only in the Comal receipt; Decide records it as an ADR in relayd):': 'Nota de decisión (sólo en el recibo de Comal; Decide la registra como ADR en relayd):',
+  'This is a structured question: Reply only sends text. To record the chosen option as an ADR the swarm respects, use Decide.': 'Es una pregunta estructurada: Reply sólo envía texto. Para registrar la opción elegida como un ADR que el enjambre respete, usa Decide.',
+  "Comal's delegation lacks the {v0} capability: relayd will reject {v1} (NOT_DELEGATED). The human must issue a delegation with it.": 'La delegación de Comal no tiene la capacidad {v0}: relayd rechazará {v1} (NOT_DELEGATED). El humano debe emitir una delegación con ella.',
+  'Structured question (agent text, untrusted): {v0}': 'Pregunta estructurada (texto del agente, no confiable): {v0}',
+  'Options:': 'Opciones:',
+  '  {v0}. {v1}{v2}': '  {v0}. {v1}{v2}',
+  ' ← chosen': ' ← elegida',
+  ' · recommended by the agent': ' · la recomienda el agente',
+  '     consequences: {v0}': '     consecuencias: {v0}',
+  'Agent recommendation: {v0} — {v1}': 'Recomendación del agente: {v0} — {v1}',
+  'Evidence cited (references, not verified): {v0}': 'Evidencia citada (referencias, sin verificar): {v0}',
+  'Scope: {v0} · Reversible: {v1} · Cost of waiting: {v2}': 'Alcance: {v0} · Reversible: {v1} · Coste de esperar: {v2}',
+  'yes': 'sí',
+  'not stated': 'no indicado',
+  'Record a decision in open-relay · decision.propose + decision.record + msg.reply': 'Registrar una decisión en open-relay · decision.propose + decision.record + msg.reply',
+  'Question {v0} from {v1} · swarm {v2}': 'Pregunta {v0} de {v1} · swarm {v2}',
+  'The message is not a structured question (no decision block): Decide will fail. Use Reply.': 'El mensaje no es una pregunta estructurada (sin bloque decision): Decide fallará. Usa Reply.',
+  'Option «{v0}» is not one of the question\'s options: Decide will fail.': 'La opción «{v0}» no es una de las de la pregunta: Decide fallará.',
+  'ADR that Comal drafted and relayd will record (accepted, signed «operator via comal»):': 'ADR que redactó Comal y registrará relayd (aceptado, firmado «operador vía comal»):',
+  '  Title: {v0}': '  Título: {v0}',
+  '  Scope: {v0}': '  Alcance: {v0}',
+  '  Answers: {v0}': '  Responde a: {v0}',
+  '  Context:': '  Contexto:',
+  '  Decision:': '  Decisión:',
+  '  Discarded alternatives:': '  Alternativas descartadas:',
+  '  Consequences:': '  Consecuencias:',
+  '  ADR digest: {v0}': '  Digest del ADR: {v0}',
+  'Reply that carries the ADR (msg.reply with decision_id; {v0} characters · sha256 {v1}…):': 'Respuesta que lleva el ADR (msg.reply con decision_id; {v0} caracteres · sha256 {v1}…):',
+  'Steps: 1. decision.propose (proposed) · 2. decision.record (accepted, in force) · 3. msg.reply with decision_id{v0}': 'Pasos: 1. decision.propose (propuesto) · 2. decision.record (aceptado, vigente) · 3. msg.reply con decision_id{v0}',
+  ' · 4. msg.ack': ' · 4. msg.ack',
+  'Already recorded for this question: {v0}': 'Ya registrado para esta pregunta: {v0}',
+  'Idempotency keys: {v0}': 'Claves de idempotencia: {v0}',
   'Idempotency key: {v0}': 'Clave de idempotencia: {v0}',
   'Reply in open-relay · {v0}': 'Responder en open-relay · {v0}',
   'relayd does not know message {v0}.': 'relayd no conoce el mensaje {v0}.',
@@ -76,15 +109,20 @@ const block = text => String(text).split('\n').map(line => `  │ ${line}`).join
 const fromLabel = message => message?.from?.role ? t('role {v0}', { v0: one(message.from.role) }) : message?.from?.kind ? one(message.from.kind) : t('operator');
 const bodyOf = message => message.pruned ? t('(body pruned by retention)') : quoted(message.body, 300);
 
-/** Un error de relayd queda con su código (INVALID_INPUT, NOT_FOUND…) en la conversación y en el recibo. */
-function relayFailure(method, error) {
+/** Un error de relayd queda con su código (INVALID_INPUT, NOT_DELEGATED…) en la conversación y en el recibo. */
+function relayFailure(method, error, extra = '') {
   if (!error?.rpc) return error;
-  return Object.assign(new Error(`relayd rejected ${method} (${error.code}): ${error.message}`), { code: error.code, retryable: error.retryable === true });
+  return Object.assign(new Error(`relayd rejected ${method} (${error.code}): ${error.message}${extra}`), { code: error.code, retryable: error.retryable === true, ...(error.capability ? { capability: error.capability } : {}) });
+}
+/** Aviso en la tarjeta si la delegación vista en el hello no trae la capacidad que el método exige. */
+function capabilityWarnings(caps, methods, warnings) {
+  if (!Array.isArray(caps)) return;
+  for (const method of methods) { const need = METHOD_CAPS[method]; if (need && !caps.includes(need)) warnings.push(t("Comal's delegation lacks the {v0} capability: relayd will reject {v1} (NOT_DELEGATED). The human must issue a delegation with it.", { v0: need, v1: method })); }
 }
 
 
 // ── Reply ────────────────────────────────────────────────────────────────────
-export async function replySummary(call, { message_id, body, ack = false, decision_note }, signal) {
+export async function replySummary(call, { message_id, body, ack = false, decision_note }, signal, { caps = () => null } = {}) {
   const warnings = [], lines = [], message = await messageOrNull(call, message_id, signal);
   if (!message) warnings.push(t('relayd does not know message {v0}: the reply will fail.', { v0: one(message_id) }));
   const swarm = message?.swarm;
@@ -93,6 +131,8 @@ export async function replySummary(call, { message_id, body, ack = false, decisi
   if (message) {
     lines.push(t('Original message {v0} ({v1}), agent text, untrusted:', { v0: one(message_id), v1: one(message.kind) }), `  ${bodyOf(message)}`);
     if (message.from?.kind === 'operator' || !message.from?.role) warnings.push(t('The original message does not come from a role: the reply unblocks no task.'));
+    const structured = decisionBlock(message);
+    if (structured) { lines.push(...decisionLines(structured)); warnings.push(t('This is a structured question: Reply only sends text. To record the chosen option as an ADR the swarm respects, use Decide.')); }
   }
   if (linked?.link === 'park') lines.push(t('Unblocks: task {v0}{v1} · {v2} → back to the queue', { v0: one(linked.task.id), v1: linked.task.title ? ` «${one(linked.task.title)}»` : '', v2: one(linked.task.state) }));
   else if (linked) { lines.push(t('Task: {v0} ({v1}) already woke up from this message.', { v0: one(linked.task.id), v1: one(linked.task.state) })); warnings.push(t('Task {v0} is no longer blocked by this question.', { v0: one(linked.task.id) })); }
@@ -100,7 +140,8 @@ export async function replySummary(call, { message_id, body, ack = false, decisi
   if (message && !delivery) warnings.push(t("The delivery is no longer pending in the operator's inbox (acknowledged or expired)."));
   lines.push(t('Exact text to send ({v0} characters · sha256 {v1}…):', { v0: body.length, v1: sha256(body).slice(0, 16) }), block(body));
   lines.push(t('Confirm delivery (msg.ack): {v0}', { v0: ack ? t('yes, the message is marked read') : t('no') }));
-  if (decision_note) lines.push(t('Decision note (only in the Comal receipt; phase 3 will store it as an ADR):'), block(decision_note));
+  if (decision_note) lines.push(t('Decision note (only in the Comal receipt; Decide records it as an ADR in relayd):'), block(decision_note));
+  capabilityWarnings(caps(), ack ? ['msg.reply', 'msg.ack'] : ['msg.reply'], warnings);
   lines.push(t('Idempotency key: {v0}', { v0: idempotencyKey('reply', { in_reply_to: message_id, body }) }));
   return { title: t('Reply in open-relay · {v0}', { v0: `msg.reply${ack ? ' + msg.ack' : ''}` }), lines, warnings, editable: 'body' };
 }
@@ -123,18 +164,19 @@ export async function reply(call, mutate, { message_id, body, ack = false, decis
     sent: { in_reply_to: message_id, reply_message_id: sent.message_id, deliveries: sent.deliveries, head_seq: sent.head_seq, idempotency_key: key, body, body_chars: body.length, body_sha256: sha256(body) },
     ack: acked, task,
     decision_note: decision_note ?? null,
-    ...(decision_note ? { decision_note_status: 'Stored only in the Comal receipt (phase 2). Phase 3 will record it as an ADR in relayd (open-relay v2.8).' } : {}),
+    ...(decision_note ? { decision_note_status: 'Stored only in the Comal receipt. To record a structured decision as an ADR in relayd, use Decide.' } : {}),
     ...(sent.outcome === 'idempotent_replay' ? { note: 'relayd recognized the key: this reply had already been sent and was not duplicated.' } : {}),
   };
 }
 
 // ── Ack ──────────────────────────────────────────────────────────────────────
 const ackTarget = ({ delivery_id, message_id }) => delivery_id || message_id;
-export async function ackSummary(call, input, signal) {
+export async function ackSummary(call, input, signal, { caps = () => null } = {}) {
   const target = ackTarget(input), message_id = input.message_id || messageOfDelivery(input.delivery_id), warnings = [];
   const message = await messageOrNull(call, message_id, signal);
   if (!message) warnings.push(t('relayd does not know message {v0}.', { v0: one(message_id) }));
   else if (!(await pendingDelivery(call, message.swarm, message_id, signal))) warnings.push(t('The delivery is no longer pending: acknowledging it changes nothing.'));
+  capabilityWarnings(caps(), ['msg.ack'], warnings);
   return { title: t('Mark as read in open-relay · msg.ack'), warnings, lines: [
     t('Delivery: {v0}', { v0: one(target) }),
     ...(message ? [t('Message {v0} ({v1}) from {v2} · swarm {v3}, agent text, untrusted:', { v0: one(message_id), v1: one(message.kind), v2: fromLabel(message), v3: one(message.swarm) }), `  ${bodyOf(message)}`] : []),
@@ -168,9 +210,10 @@ function planLines(got, warnings) {
   return lines;
 }
 
-export async function approveSummary(call, { proposal_id, digest: wanted }, signal) {
+export async function approveSummary(call, { proposal_id, digest: wanted }, signal, { caps = () => null } = {}) {
   const warnings = [t('Applies immediately: on approval, relayd creates the roles, grants and tasks of the plan with no further step.')];
   const got = await planOrNull(call, proposal_id, signal);
+  capabilityWarnings(caps(), ['plan.approve'], warnings);
   if (!got) return { title: t('Approve plan in open-relay · plan.approve'), lines: [t('Proposal {v0}', { v0: one(proposal_id) }), t('Digest: {v0}', { v0: one(wanted) })], warnings: [...warnings, t('relayd does not know proposal {v0}: the approval will fail.', { v0: one(proposal_id) })] };
   const lines = planLines(got, warnings), current = got.proposal?.digest;
   lines.push(t('Approved digest: {v0}', { v0: one(wanted) }) + (current === wanted ? t(' (matches the current one)') : ''));
@@ -184,8 +227,9 @@ export async function approve(mutate, { proposal_id, digest: wanted }, signal) {
   catch (error) { throw relayFailure('plan.approve', error); }
 }
 
-export async function rejectSummary(call, { proposal_id, reason }, signal) {
+export async function rejectSummary(call, { proposal_id, reason }, signal, { caps = () => null } = {}) {
   const warnings = [], got = await planOrNull(call, proposal_id, signal);
+  capabilityWarnings(caps(), ['plan.reject'], warnings);
   const lines = got ? planLines(got, warnings) : [t('Proposal {v0}', { v0: one(proposal_id) })];
   if (!got) warnings.push(t('relayd does not know proposal {v0}: the rejection will fail.', { v0: one(proposal_id) }));
   lines.push(t('Exact reason the lead receives (it is woken up with it):'), block(reason));
@@ -203,3 +247,104 @@ function decision(result, key) {
     proposal: { proposal_id: proposal.proposal_id, status: proposal.status, approver: proposal.approver ?? null, digest: proposal.digest, reason: proposal.reason ? excerpt(proposal.reason, 500) : null, tasks: proposal.tasks, roles: proposal.roles },
     steps: (result.steps || []).slice(0, 40).map(step => ({ kind: step.kind, id: step.id, method: step.method, action: step.action, result: step.result ?? null })) };
 }
+
+// ── Decide (fase 3) ─────────────────────────────────────────────────────────
+// Respuesta a una pregunta estructurada que queda como ADR en relayd. El HOST redacta
+// el ADR (decision.mjs) con la pregunta tal como la guarda relayd, la opción elegida y
+// la nota; la tarjeta lo muestra entero con su digest y sólo el humano la aprueba
+// (confirm:'always'). Tres mutaciones con claves estables derivadas de la misma
+// entrada: un reintento de la misma tarjeta retoma donde quedó sin duplicar nada.
+const yesNo = value => value ? t('yes') : t('no');
+/** Líneas legibles del bloque `decision` (texto del agente, ya limpio y acotado). */
+export function decisionLines(block, chosen = null) {
+  const lines = [t('Structured question (agent text, untrusted): {v0}', { v0: `«${block.question}»` }), t('Options:')];
+  block.options.forEach((item, index) => {
+    lines.push(t('  {v0}. {v1}{v2}', { v0: index + 1, v1: `«${item.label}»`, v2: `${item.label === chosen?.label ? t(' ← chosen') : ''}${item.label === block.recommendation?.option ? t(' · recommended by the agent') : ''}` }));
+    if (item.consequences) lines.push(t('     consequences: {v0}', { v0: excerpt(item.consequences, 400) }));
+  });
+  if (block.recommendation) lines.push(t('Agent recommendation: {v0} — {v1}', { v0: `«${block.recommendation.option}»`, v1: excerpt(block.recommendation.why, 400) }));
+  if (block.evidence.length) lines.push(t('Evidence cited (references, not verified): {v0}', { v0: block.evidence.map(item => `${item.kind}:${one(item.ref)}`).join(' · ') }));
+  lines.push(t('Scope: {v0} · Reversible: {v1} · Cost of waiting: {v2}', { v0: block.scope, v1: yesNo(block.reversible), v2: block.cost_of_waiting ? excerpt(block.cost_of_waiting, 300) : t('not stated') }));
+  return lines;
+}
+const decideBase = ({ message_id, option, body, decision_note, scope }) => digest({ action: 'decide', message_id, option, body, decision_note: decision_note ?? null, scope: scope ?? null }).slice(0, 48);
+export const decideKeys = input => { const base = decideBase(input); return { propose: `comal-adr-propose-${base}`, record: `comal-adr-record-${base}`, reply: `comal-decide-reply-${base}`, ack: idempotencyKey('ack', { delivery_id: input.message_id }) }; };
+const scopeText = scope => scope.id ? `${scope.kind}:${one(scope.id)}` : scope.kind;
+
+/** Lo que la tarjeta y la ejecución comparten: mensaje, bloque, opción, tarea, alcance y ADR. */
+async function prepareDecision(call, { message_id, option, decision_note, scope }, signal) {
+  const message = await messageOrNull(call, message_id, signal);
+  if (!message) return { message: null };
+  const block = decisionBlock(message), chosen = chosenOption(block, option);
+  const linked = block ? await taskForMessage(call, message.swarm, message_id, signal) : null;
+  const { scope: adrScopeValue, note } = block ? adrScope(block, { scope, message, task: linked?.task }) : { scope: null, note: null };
+  const adr = chosen ? draftAdr({ message, block, option, decision_note, scope: adrScopeValue }) : null;
+  return { message, block, chosen, linked, adr, scopeNote: note };
+}
+async function existingAdrs(call, message, signal) {
+  try { const { decisions = [] } = await call('decision.list', { swarm_id: message.swarm, limit: 200 }, signal); return decisions.filter(item => item.answers === message.id); }
+  catch (error) { if (error.rpc) return []; throw error; }
+}
+
+export async function decideSummary(call, input, signal, { caps = () => null } = {}) {
+  const { message_id, option, body, ack = false } = input, warnings = [], lines = [];
+  const title = t('Record a decision in open-relay · decision.propose + decision.record + msg.reply');
+  const { message, block: structured, chosen, linked, adr, scopeNote } = await prepareDecision(call, input, signal);
+  if (!message) return { title, lines: [t('Delivery: {v0}', { v0: one(message_id) })], warnings: [t('relayd does not know message {v0}: the reply will fail.', { v0: one(message_id) })] };
+  lines.push(t('Question {v0} from {v1} · swarm {v2}', { v0: one(message_id), v1: fromLabel(message), v2: one(message.swarm) }));
+  if (!structured) warnings.push(t('The message is not a structured question (no decision block): Decide will fail. Use Reply.'));
+  else {
+    lines.push(...decisionLines(structured, chosen));
+    if (!chosen) warnings.push(t('Option «{v0}» is not one of the question\'s options: Decide will fail.', { v0: one(option) }));
+  }
+  if (linked?.link === 'park') lines.push(t('Unblocks: task {v0}{v1} · {v2} → back to the queue', { v0: one(linked.task.id), v1: linked.task.title ? ` «${one(linked.task.title)}»` : '', v2: one(linked.task.state) }));
+  if (scopeNote) warnings.push(scopeNote);
+  if (adr) {
+    lines.push(t('ADR that Comal drafted and relayd will record (accepted, signed «operator via comal»):'));
+    lines.push(t('  Title: {v0}', { v0: adr.title }), t('  Scope: {v0}', { v0: scopeText(adr.scope) }), t('  Answers: {v0}', { v0: one(adr.answers) }));
+    lines.push(t('  Context:'), block4(adr.context), t('  Decision:'), block4(adr.decision));
+    if (adr.alternatives.length) lines.push(t('  Discarded alternatives:'), block4(adr.alternatives.map(item => `${item.option}: ${item.why_rejected}`).join('\n')));
+    lines.push(t('  Consequences:'), block4(adr.consequences), t('  ADR digest: {v0}', { v0: adrDigest(adr) }));
+    for (const item of (await existingAdrs(call, message, signal)).slice(0, 4)) warnings.push(t('Already recorded for this question: {v0}', { v0: `${one(item.id)} (${one(item.status)}${item.in_force ? ', in force' : ''}) «${one(item.title)}»` }));
+  }
+  lines.push(t('Reply that carries the ADR (msg.reply with decision_id; {v0} characters · sha256 {v1}…):', { v0: body.length, v1: sha256(body).slice(0, 16) }), block(body));
+  lines.push(t('Steps: 1. decision.propose (proposed) · 2. decision.record (accepted, in force) · 3. msg.reply with decision_id{v0}', { v0: ack ? t(' · 4. msg.ack') : '' }));
+  if (message && !(await pendingDelivery(call, message.swarm, message_id, signal))) warnings.push(t("The delivery is no longer pending in the operator's inbox (acknowledged or expired)."));
+  capabilityWarnings(caps(), ['decision.propose', 'decision.record', 'msg.reply', ...(ack ? ['msg.ack'] : [])], warnings);
+  const keys = decideKeys(input);
+  lines.push(t('Idempotency keys: {v0}', { v0: [keys.propose, keys.record, keys.reply].join(' · ') }));
+  return { title, lines, warnings, editable: 'body' };
+}
+const block4 = text => String(text).split('\n').map(line => `    │ ${line}`).join('\n');
+const fail = (code, message) => Object.assign(new Error(message), { code });
+
+export async function decide(call, mutate, input, signal) {
+  const { message_id, option, body, ack = false } = input, keys = decideKeys(input);
+  const { message, block: structured, chosen, linked, adr } = await prepareDecision(call, input, signal);
+  if (!message) throw fail('NOT_FOUND', `relayd does not know message ${one(message_id)}.`);
+  if (!structured) throw fail('DECISION_NOT_STRUCTURED', `Message ${one(message_id)} is not a structured question (it has no decision block): use Reply.`);
+  if (!chosen || !adr) throw fail('DECISION_UNKNOWN_OPTION', `«${one(option)}» is not one of the options: ${structured.options.map(item => `«${item.label}»`).join(', ')}.`);
+  let proposed, recorded, sent;
+  try { proposed = await mutate('decision.propose', { idempotency_key: keys.propose, adr }, signal); }
+  catch (error) { throw relayFailure('decision.propose', error); }
+  const id = proposed.decision?.id;
+  try { recorded = await mutate('decision.record', { idempotency_key: keys.record, decision_id: id }, signal); }
+  catch (error) { throw relayFailure('decision.record', error, ` (ADR ${id} stays proposed; retrying the same card resumes without duplicating it)`); }
+  try { sent = await mutate('msg.reply', { idempotency_key: keys.reply, in_reply_to: message_id, body, decision_id: id }, signal); }
+  catch (error) { throw relayFailure('msg.reply', error, ` (ADR ${id} is recorded and in force; retrying the same card sends the reply without duplicating anything)`); }
+  let acked = null;
+  if (ack) {
+    try { const result = await mutate('msg.ack', { idempotency_key: keys.ack, delivery_id: message_id }, signal); acked = { status: 'applied', outcome: result.outcome, delivery_id: result.delivery_id, state: result.state }; }
+    catch (error) { acked = { status: 'failed', code: error.code || 'ERROR', message: String(error.message).slice(0, 300) }; }
+  }
+  const view = recorded.decision || proposed.decision || {};
+  const replayed = [proposed, recorded, sent].every(item => item.outcome === 'idempotent_replay');
+  return {
+    truncated: false, status: replayed ? 'replayed' : 'applied', outcome: sent.outcome,
+    decision: { id, status: view.status, in_force: view.in_force, title: view.title, scope: view.scope, answers: view.answers ?? null, proposed_via: view.proposed_via ?? null, accepted_via: view.accepted_via ?? null, adr_digest: adrDigest(adr), propose_outcome: proposed.outcome, record_outcome: recorded.outcome },
+    sent: { in_reply_to: message_id, decision_id: id, reply_message_id: sent.message_id, deliveries: sent.deliveries, head_seq: sent.head_seq, body, body_chars: body.length, body_sha256: sha256(body) },
+    ack: acked, task: linked ? { id: linked.task.id, state: linked.task.state, link: linked.link } : null,
+    idempotency_keys: keys,
+    ...(replayed ? { note: 'relayd recognized the keys: this decision and its reply had already been recorded and were not duplicated.' } : {}),
+  };
+}

package/src/plugins/open-relay/client.mjs

@@ -1,57 +1,101 @@
 import net from 'node:net';
+import os from 'node:os';
 import path from 'node:path';
 import { constants } from 'node:fs';
-import { open } from 'node:fs/promises';
+import { open, stat } from 'node:fs/promises';
 
 // Cliente JSON-RPC 2.0 por líneas sobre el socket administrativo de relayd
-// (`<control>/admin/relay.sock`). Las listas blancas de métodos viven aquí: 16
-// lecturas (`call`) y, desde la fase 2, cuatro mutaciones (`mutate`) que el plugin
-// sólo usa tras la tarjeta de confirmación humana. Cualquier otro método se rechaza
-// sin llegar al socket: ningún job, swarm.create, grant ni sesión.
+// (`<control>/admin/relay.sock`). Desde la fase 3 (open-relay ≥ 2.8) se autentica con
+// una sesión DELEGADA (`relay session issue-delegate --client comal`), nunca con
+// `admin.token`: relayd firma lo que hace como «operador vía comal» y sólo admite los
+// métodos de sus capacidades. Las listas blancas de métodos siguen aquí: 19 lecturas
+// (`call`) y seis mutaciones (`mutate`) que el plugin sólo usa tras la tarjeta de
+// confirmación humana. Cualquier otro método se rechaza sin llegar al socket.
 export const READ_METHODS = Object.freeze(new Set([
   'daemon.status', 'daemon.version', 'swarm.list', 'swarm.status', 'task.get', 'task.list',
   'msg.inbox', 'msg.get', 'msg.wait', 'plan.list', 'plan.get', 'job.list', 'job.get', 'job.logs',
-  'receipt.get', 'events.since',
+  'receipt.get', 'events.since', 'events.wait', 'decision.list', 'decision.get',
 ]));
-export const WRITE_METHODS = Object.freeze(new Set(['msg.reply', 'msg.ack', 'plan.approve', 'plan.reject']));
-// El alcance de idempotencia del canal admin es compartido ("operator") por todos sus
-// clientes: las claves de Comal llevan prefijo propio y caben en los 128 de relayd.
+export const WRITE_METHODS = Object.freeze(new Set(['msg.reply', 'msg.ack', 'plan.approve', 'plan.reject', 'decision.propose', 'decision.record']));
+// Capacidad de la delegación que relayd exige para cada mutación (lecturas: `read`).
+export const METHOD_CAPS = Object.freeze({ 'msg.reply': 'converse', 'msg.ack': 'converse', 'plan.approve': 'plans', 'plan.reject': 'plans', 'decision.propose': 'decide', 'decision.record': 'decide' });
+export const RECOMMENDED_CAPS = 'read,converse,plans,decide';
+// El `client` del hello debe ser exactamente el de la delegación: así un token emitido
+// para otro programa (p. ej. la web) no sirve a Comal.
+export const DELEGATE_CLIENT = 'comal';
+// Las claves de idempotencia son del alcance de la sesión delegada; el prefijo comal-
+// se mantiene para reconocerlas en el log de relayd.
 export const IDEMPOTENCY_KEY = /^comal-[A-Za-z0-9][A-Za-z0-9_.:-]{0,121}$/;
 export const PROTOCOL_VERSION = 1;
+const TOKEN_FORMAT = /^orly_[0-9a-f]{64}$/;
 // relayd acota cada frame a 1 MiB por omisión; las respuestas de lectura del CLI admiten 16×.
 const MAX_RESPONSE_BYTES = 16 << 20;
 const fail = (code, message, extra = {}) => Object.assign(new Error(message), { code, ...extra });
 
-export function controlPaths(controlDir) {
-  const root = path.resolve(controlDir);
-  return { root, admin: path.join(root, 'admin'), socket: path.join(root, 'admin', 'relay.sock'), token: path.join(root, 'admin', 'admin.token') };
+export function controlPaths(controlDir, tokenFile) {
+  const root = path.resolve(controlDir), admin = path.join(root, 'admin');
+  return { root, admin, socket: path.join(admin, 'relay.sock'), adminToken: path.join(admin, 'admin.token'), token: tokenFile ? path.resolve(tokenFile) : path.join(root, 'comal.token') };
 }
 
-/** Lee el token en cada conexión: relayd lo reescribe en cada arranque. Nunca se expone. */
-async function readToken(file) {
+const shellWord = value => /^[A-Za-z0-9_./:=@%+-]+$/.test(value) ? value : `'${String(value).replace(/'/g, `'\\''`)}'`;
+const principal = () => { try { return os.userInfo().username || 'operator'; } catch { return 'operator'; } };
+/** El comando exacto que el humano corre (una vez) para emitir el token de Comal. */
+export function issueCommand(paths, caps = RECOMMENDED_CAPS) {
+  return `relay --control-dir ${shellWord(paths.root)} session issue-delegate --principal ${shellWord(principal())} --client ${DELEGATE_CLIENT} --caps ${caps} --ttl 30d --out ${shellWord(paths.token)}`;
+}
+const reissue = paths => `Remove ${paths.token} and issue a new one: ${issueCommand(paths)}`;
+
+/**
+ * Lee el token delegado en cada conexión (el humano puede reemitirlo sin recargar el
+ * plugin). Nunca lee `admin.token`: ni como respaldo ni si la ruta configurada lo es.
+ * El valor nunca sale de aquí salvo hacia el hello.
+ */
+async function readToken(paths) {
+  if (paths.token === paths.adminToken || path.dirname(paths.token) === paths.admin) throw fail('RELAY_ADMIN_TOKEN_REFUSED', `Comal never authenticates with relayd's admin token. Use a delegate token outside ${paths.admin}: ${issueCommand({ ...paths, token: path.join(paths.root, 'comal.token') })}`);
   let handle;
   try {
-    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    handle = await open(paths.token, constants.O_RDONLY | constants.O_NOFOLLOW);
     const info = await handle.stat(), uid = process.getuid?.();
-    if (!info.isFile() || info.size > 4096 || (uid !== undefined && info.uid !== uid) || (info.mode & 0o077)) throw fail('RELAY_TOKEN_UNSAFE', "relayd's admin token is not a private (0600) file owned by the user.");
-    const token = (await handle.readFile('utf8')).trim();
-    if (!token) throw fail('RELAY_UNAVAILABLE', "relayd's admin token is empty.");
+    if (!info.isFile() || info.size > 4096 || (uid !== undefined && info.uid !== uid) || (info.mode & 0o077)) throw fail('RELAY_TOKEN_UNSAFE', `The delegate token ${paths.token} is not a private (0600) file owned by the user.`);
+    // Un enlace duro a admin.token también se rechaza (sólo se mira su inodo, nunca su contenido).
+    const admin = await stat(paths.adminToken).catch(() => null);
+    if (admin && admin.ino === info.ino && admin.dev === info.dev) throw fail('RELAY_ADMIN_TOKEN_REFUSED', `${paths.token} is relayd's admin token, not a delegate session. ${reissue(paths)}`);
+    const token = (await handle.readFile('utf8')).replace(/\r?\n$/, '');
+    if (!TOKEN_FORMAT.test(token)) throw fail('RELAY_TOKEN_INVALID', `The delegate token ${paths.token} does not have the orly_<64 hex> format. ${reissue(paths)}`);
     return token;
   } catch (error) {
-    if (error.code === 'ENOENT') throw fail('RELAY_UNAVAILABLE', 'relayd is not running in that control directory (the admin token is missing).');
+    if (error.code === 'ENOENT') {
+      const running = await stat(paths.adminToken).then(() => true, () => false);
+      throw fail('RELAY_DELEGATE_MISSING', running
+        ? `Comal has no delegate token for relayd at ${paths.token} (Comal never uses admin.token). Ask the human to issue it once: ${issueCommand(paths)}`
+        : `No delegate token at ${paths.token}, and relayd does not seem to be running in ${paths.root}. Start relayd, then issue the token: ${issueCommand(paths)}`);
+    }
+    if (error.code === 'ELOOP') throw fail('RELAY_TOKEN_UNSAFE', `The delegate token ${paths.token} is a symlink; use a regular 0600 file.`);
     throw error;
   } finally { await handle?.close(); }
 }
 
+/** Mensaje legible para un error de relayd; NOT_DELEGATED y UNAUTHORIZED dicen qué hacer. */
+function rpcFailure(method, data, paths) {
+  const code = data.code || 'RELAY_ERROR', text = String(data.message || 'relayd error').slice(0, 500);
+  if (code === 'NOT_DELEGATED') {
+    const capability = METHOD_CAPS[method] || /capacidad (\w+)/.exec(text)?.[1] || (READ_METHODS.has(method) ? 'read' : null);
+    return fail(code, `${text} — Comal's delegate session cannot do ${method}${capability ? ` (missing capability: ${capability})` : ''}. Not retried: ask the human for a delegation with that capability. ${reissue(paths)}`, { retryable: false, rpc: true, capability });
+  }
+  // En una llamada, UNAUTHORIZED con «sesión revocada/expirada» es la delegación; en decision.get es «no existe».
+  if (code === 'UNAUTHORIZED' && (method === 'daemon.hello' || /revoc|expir/i.test(text))) return fail(code, `relayd rejected Comal's delegate token (${text}): it was revoked, expired, or issued for a client other than "${DELEGATE_CLIENT}". ${reissue(paths)}`, { retryable: false, rpc: true });
+  return fail(code, text, { retryable: data.retryable === true, rpc: true });
+}
+
 /** Una conexión autenticada. Las esperas largas usan una conexión propia. */
 export class RelayConnection {
-  constructor({ controlDir, client = 'comal', timeoutMs = 10000, connect = options => net.createConnection(options) }) {
-    Object.assign(this, { paths: controlPaths(controlDir), client, timeoutMs, connect });
+  constructor({ controlDir, tokenFile, client = DELEGATE_CLIENT, timeoutMs = 10000, connect = options => net.createConnection(options) }) {
+    Object.assign(this, { paths: controlPaths(controlDir, tokenFile), client, timeoutMs, connect });
     this.pending = new Map(); this.nextId = 1; this.closed = false; this.socket = null; this.session = null;
   }
   async open(signal) {
     signal?.throwIfAborted();
-    const token = await readToken(this.paths.token);
+    const token = await readToken(this.paths);
     const socket = this.socket = this.connect({ path: this.paths.socket });
     let buffer = Buffer.alloc(0);
     await new Promise((resolve, reject) => {
@@ -75,10 +119,16 @@ export class RelayConnection {
     });
     socket.on('error', error => this.#fail(fail('RELAY_DISCONNECTED', `Connection to relayd lost (${error.code || error.message}).`)));
     socket.on('close', () => this.#fail(fail('RELAY_DISCONNECTED', 'relayd closed the connection.')));
-    try { this.session = await this.#request('daemon.hello', { protocol_versions: [PROTOCOL_VERSION], token, client: this.client }, { signal }); }
-    catch (error) { this.close(); throw error; }
+    try {
+      const session = await this.#request('daemon.hello', { protocol_versions: [PROTOCOL_VERSION], token, client: this.client }, { signal });
+      // Sin `delegate` el token es del operador directo (p. ej. una copia de admin.token): no se usa.
+      if (!session?.delegate) throw fail('RELAY_ADMIN_TOKEN_REFUSED', `The token in ${this.paths.token} is a direct operator token, not a delegate session; Comal only operates through a delegation. ${reissue(this.paths)}`);
+      this.session = session;
+    } catch (error) { this.close(); throw error; }
     return this.session;
   }
+  /** Lo que relayd dijo de la delegación en el hello: principal, client, caps, persistent. */
+  get delegate() { return this.session?.delegate || null; }
   #fail(error) {
     if (this.closed) return; this.closed = true; this.error = error;
     for (const entry of this.pending.values()) entry.finish(null, error);
@@ -89,7 +139,7 @@ export class RelayConnection {
     if (!READ_METHODS.has(method)) return Promise.reject(fail('RELAY_METHOD_FORBIDDEN', `Method not allowed for reading: ${method}`));
     return this.#request(method, params, { signal, timeoutMs });
   }
-  /** Sólo las cuatro mutaciones de la lista blanca y siempre con una clave de idempotencia de Comal. */
+  /** Sólo las mutaciones de la lista blanca y siempre con una clave de idempotencia de Comal. */
   mutate(method, params = {}, { signal, timeoutMs } = {}) {
     if (!WRITE_METHODS.has(method)) return Promise.reject(fail('RELAY_METHOD_FORBIDDEN', `Method not allowed for Comal: ${method}`));
     if (typeof params?.idempotency_key !== 'string' || !IDEMPOTENCY_KEY.test(params.idempotency_key)) return Promise.reject(fail('RELAY_IDEMPOTENCY_KEY', 'Every mutation needs a comal-… idempotency_key of up to 128 characters.'));
@@ -103,7 +153,7 @@ export class RelayConnection {
       const finish = (message, error) => {
         clearTimeout(timer); signal?.removeEventListener('abort', abort);
         if (error) return reject(error);
-        if (message.error) { const data = message.error.data || {}; return reject(fail(data.code || 'RELAY_ERROR', String(data.message || message.error.message || 'relayd error').slice(0, 500), { retryable: data.retryable === true, rpc: true })); }
+        if (message.error) return reject(rpcFailure(method, { message: message.error.message, ...(message.error.data || {}) }, this.paths));
         resolve(message.result);
       };
       const abort = () => { if (this.pending.delete(id)) finish(null, signal.reason); };
@@ -116,21 +166,29 @@ export class RelayConnection {
   close() { this.#fail(fail('RELAY_DISCONNECTED', 'Connection closed by Comal.')); }
 }
 
-// Errores tras los cuales conviene reconectar (relayd reiniciado, sesión vencida, token nuevo).
-export const reconnectable = error => ['RELAY_DISCONNECTED', 'RELAY_UNAVAILABLE', 'RELAY_TIMEOUT', 'UNAUTHORIZED', 'RELAY_PROTOCOL'].includes(error?.code);
+// Errores tras los cuales conviene reconectar (relayd reiniciado o recuperándose).
+// UNAUTHORIZED, NOT_DELEGATED y los del archivo del token necesitan al humano.
+export const reconnectable = error => ['RELAY_DISCONNECTED', 'RELAY_UNAVAILABLE', 'RELAY_TIMEOUT', 'RELAY_PROTOCOL', 'UNAVAILABLE'].includes(error?.code);
+// Errores que ninguna espera arregla: hace falta otra delegación o que el humano corrija el token.
+export const needsHuman = error => ['NOT_DELEGATED', 'UNAUTHORIZED', 'RELAY_DELEGATE_MISSING', 'RELAY_ADMIN_TOKEN_REFUSED', 'RELAY_TOKEN_UNSAFE', 'RELAY_TOKEN_INVALID'].includes(error?.code);
 
 /** Conexión de consultas compartida, con reconexión perezosa y un reintento (las lecturas son idempotentes). */
 export class RelayClient {
-  constructor({ controlDir, client = 'comal', timeoutMs = 10000, connect }) {
-    Object.assign(this, { controlDir, client, timeoutMs, connect });
-    this.connection = null; this.connecting = null; this.closed = false; this.connects = 0; this.lastError = null;
+  constructor({ controlDir, tokenFile, client = DELEGATE_CLIENT, timeoutMs = 10000, connect }) {
+    Object.assign(this, { controlDir, tokenFile, client, timeoutMs, connect, paths: controlPaths(controlDir, tokenFile) });
+    this.connection = null; this.connecting = null; this.closed = false; this.connects = 0; this.lastError = null; this.session = null;
   }
-  connection_options() { return { controlDir: this.controlDir, client: this.client, timeoutMs: this.timeoutMs, ...(this.connect ? { connect: this.connect } : {}) }; }
-  /** Conexión nueva y dedicada (para msg.wait / swarm.status con if_changed). */
+  connection_options() { return { controlDir: this.controlDir, tokenFile: this.tokenFile, client: this.client, timeoutMs: this.timeoutMs, ...(this.connect ? { connect: this.connect } : {}) }; }
+  /** La delegación vista en el último hello (sin el token). */
+  get delegate() { return this.session?.delegate || null; }
+  issueCommand() { return issueCommand(this.paths); }
+  /** Conexión nueva y dedicada (para events.wait). */
   async dedicated(signal) {
     if (this.closed) throw fail('RELAY_CLOSED', 'open-relay plugin closed.');
     const connection = new RelayConnection(this.connection_options());
-    await connection.open(signal); this.connects++; return connection;
+    try { await connection.open(signal); }
+    catch (error) { this.lastError = { code: error.code || 'ERROR', message: String(error.message).slice(0, 600), at: new Date().toISOString() }; throw error; }
+    this.connects++; this.session = connection.session; return connection;
   }
   async #shared(signal) {
     if (this.connection && !this.connection.closed) return this.connection;
@@ -148,7 +206,7 @@ export class RelayClient {
     for (let attempt = 0; ; attempt++) {
       try { const connection = await this.#shared(options.signal); const result = await connection[kind](method, params, options); this.lastError = null; return result; }
       catch (error) {
-        this.lastError = { code: error.code || 'ERROR', message: String(error.message).slice(0, 300), at: new Date().toISOString() };
+        this.lastError = { code: error.code || 'ERROR', message: String(error.message).slice(0, 600), at: new Date().toISOString() };
         if (attempt || !reconnectable(error) || options.signal?.aborted) throw error;
         this.connection?.close(); this.connection = null;
       }

package/src/plugins/open-relay/decision.mjs

@@ -0,0 +1,88 @@
+import { clean } from './bound.mjs';
+import { digest } from '../../operations.mjs';
+
+// Preguntas estructuradas (`message.decision`, open-relay ≥ 2.8) y el ADR que Comal
+// redacta a partir de la opción elegida. Todo el bloque `decision` es texto de un
+// agente: se limpia (sin controles, escapes de terminal ni bidi), se acota y se marca
+// como no confiable. El ADR lo arma el HOST, determinista, con datos de relayd y lo que
+// el humano aprueba en la tarjeta (opción, nota, texto de la respuesta): el modelo no
+// redacta el registro ni lo puede aprobar.
+const EVIDENCE_KINDS = new Set(['task', 'attempt', 'receipt', 'file', 'commit', 'message', 'decision']);
+const SCOPES = new Set(['task', 'swarm', 'project']);
+const line = (value, limit) => cut(clean(value).replace(/\s+/g, ' ').trim(), limit);
+const text = (value, limit) => cut(clean(value).replace(/[ \t]+\n/g, '\n').trim(), limit);
+function cut(value, limit) { const chars = [...value]; return chars.length > limit ? chars.slice(0, limit).join('') + '…' : value; }
+/** Recorta a `max` bytes UTF-8 sin partir un carácter (relayd mide en bytes). */
+export function cutBytes(value, max) {
+  if (Buffer.byteLength(value) <= max) return value;
+  let out = '', size = 0; const room = max - 3;
+  for (const char of value) { const bytes = Buffer.byteLength(char); if (size + bytes > room) break; out += char; size += bytes; }
+  return out + '…';
+}
+
+/** El bloque `decision` de un mensaje, limpio y acotado, o null si no es una pregunta estructurada. */
+export function decisionBlock(message) {
+  const raw = message?.kind === 'question' ? message.decision : null;
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.options)) return null;
+  const options = raw.options.slice(0, 4).filter(item => item && typeof item.label === 'string').map(item => ({ label: line(item.label, 120), consequences: text(item.consequences ?? '', 1024) }));
+  if (!options.length) return null;
+  const recommendation = raw.recommendation && typeof raw.recommendation === 'object' ? { option: line(raw.recommendation.option ?? '', 120), why: text(raw.recommendation.why ?? '', 1024) } : null;
+  return {
+    untrusted: true,
+    question: line(raw.question ?? '', 200),
+    options,
+    recommendation,
+    evidence: (Array.isArray(raw.evidence) ? raw.evidence : []).slice(0, 16).map(item => ({ kind: EVIDENCE_KINDS.has(item?.kind) ? item.kind : 'other', ref: line(item?.ref ?? '', 256) })),
+    scope: SCOPES.has(raw.scope) ? raw.scope : 'task',
+    reversible: raw.reversible === true,
+    cost_of_waiting: text(raw.cost_of_waiting ?? '', 600),
+  };
+}
+
+/** Resumen de una línea para avisos y el buzón (al modelo: inglés fijo). */
+export function decisionLine(block) {
+  if (!block) return null;
+  const recommended = block.recommendation?.option;
+  return `«${block.question}» · options: ${block.options.map(item => `«${item.label}»${item.label === recommended ? ' (recommended by the agent)' : ''}`).join(' | ')} · scope ${block.scope} · ${block.reversible ? 'reversible' : 'not reversible'}`;
+}
+
+/** La opción elegida (por su label exacto, sin distinguir espacios de más) o null. */
+export const chosenOption = (block, option) => block?.options.find(item => item.label === line(option ?? '', 120)) || null;
+
+/** Alcance del ADR: el pedido por el humano o el de la pregunta. Una pregunta de tarea sin tarea ligada cae al swarm. */
+export function adrScope(block, { scope, message, task }) {
+  const kind = SCOPES.has(scope) ? scope : block?.scope || 'task';
+  if (kind === 'project') return { scope: { kind: 'project' }, note: null };
+  if (kind === 'task' && task?.id) return { scope: { kind: 'task', id: task.id }, note: null };
+  return { scope: { kind: 'swarm', id: message.swarm }, note: kind === 'task' ? 'No task is linked to this question: the ADR applies to the whole swarm.' : null };
+}
+
+/**
+ * Borrador del ADR (forma de `decision.propose.adr`), determinista: mismos datos de
+ * relayd y misma entrada dan el mismo ADR y el mismo digest (lo que la tarjeta muestra
+ * es lo que se envía). Respeta los topes de relayd: título ≤ 200 B, textos ≤ 4 KiB,
+ * alternativas ≤ 1 KiB, ≤ 16 KiB en total.
+ */
+export function draftAdr({ message, block, option, decision_note, scope }) {
+  const chosen = chosenOption(block, option);
+  if (!chosen) return null;
+  const from = message.from?.role ? `role ${line(message.from.role, 120)}` : 'the operator';
+  const note = decision_note ? text(decision_note, 2000) : '';
+  const evidence = block.evidence.map(item => `${item.kind}:${item.ref}`).join(', ');
+  const title = cutBytes(line(`${block.question} → ${chosen.label}`, 400), 200);
+  const decision = cutBytes([`Chosen option: ${chosen.label}.`, note].filter(Boolean).join('\n\n'), 4096);
+  const consequences = cutBytes(chosen.consequences || 'Not stated by the question.', 4096);
+  const alternatives = block.options.filter(item => item !== chosen).map(item => ({ option: cutBytes(item.label, 120), why_rejected: cutBytes(`Not chosen by the operator.${item.consequences ? ` Its consequences would have been: ${item.consequences}` : ''}`, 1024) }));
+  const fixed = Buffer.byteLength(title + decision + consequences) + alternatives.reduce((sum, item) => sum + Buffer.byteLength(item.option + item.why_rejected), 0);
+  const context = cutBytes([
+    `Structured question from ${from} (message ${line(message.id, 200)}, swarm ${line(message.swarm, 200)}); the agent's text is quoted as it arrived:`,
+    block.question,
+    'Options:', ...block.options.map(item => `- ${item.label}: ${item.consequences}`),
+    block.recommendation ? `Agent recommendation: ${block.recommendation.option} (${block.recommendation.why})` : null,
+    `Reversible: ${block.reversible ? 'yes' : 'no'}. Cost of waiting: ${(block.cost_of_waiting || 'not stated').replace(/[.\s]+$/, '')}.`,
+    evidence ? `Evidence cited: ${evidence}.` : null,
+  ].filter(Boolean).join('\n'), Math.min(4096, 16000 - fixed));
+  return { title, context, decision, alternatives, consequences, scope, answers: message.id };
+}
+
+export const adrDigest = adr => digest(adr);

package/src/plugins/open-relay/dossier.mjs

@@ -3,11 +3,14 @@ import { constants } from 'node:fs';
 import { open, readdir } from 'node:fs/promises';
 import { Truncation, clean, excerpt } from './bound.mjs';
 import { messageOrNull, messageOfDelivery, taskForMessage, pendingDelivery } from './lookup.mjs';
+import { decisionBlock } from './decision.mjs';
 
 // Expediente de decisión: todo lo que el humano necesita para responder una
 // pregunta del enjambre, armado por el host y acotado. El texto del agente va
-// marcado como no confiable; las decisiones relacionadas salen de los ADR del
-// proyecto con una búsqueda simple de términos. El expediente va al modelo: inglés fijo.
+// marcado como no confiable (también el bloque `decision` de una pregunta estructurada);
+// las decisiones relacionadas salen del registro de relayd (ADR vigentes del swarm y los
+// que ya responden esta pregunta) y de los ADR del proyecto con una búsqueda simple de
+// términos. El expediente va al modelo: inglés fijo.
 const STOP = new Set(('puedo puede pueden quiero quieres debes debemos deberia hacer hacemos tiene tienen tengo sobre entre desde hasta donde cuando porque como para pero todos todas esto esta este estos estas otra otro otros ahora antes despues mismo cada solo tambien bien sigue seguir cambiar cambio usar usamos hacia segun mientras ignora reglas borra ' +
   'about after before could would should there their these those which while where with without from into this that what when your yours have will cannot please change using').split(' '));
 const fold = text => String(text || '').normalize('NFD').replace(/\p{M}+/gu, '').toLowerCase();
@@ -70,6 +73,7 @@ export async function buildDossier(call, { delivery_id, message_id }, { adrDirs,
     message_id: id, delivery_id: delivery?.delivery_id || delivery_id || null, delivery_state: delivery ? 'pending' : 'not_pending',
     kind: message.kind, from: message.from?.role ? `role:${clean(message.from.role)}` : clean(message.from?.kind || 'operator'), swarm, sent_at: message.sent_at, in_reply_to: message.in_reply_to ?? null,
     body: message.pruned ? '(body pruned by retention)' : cut.text(message.body, 4000, 'question.body'),
+    decision: decisionBlock(message),
   };
   if (!delivery) mismatches.push("The delivery is no longer pending in the operator's inbox (acknowledged or expired).");
 
@@ -107,13 +111,27 @@ export async function buildDossier(call, { delivery_id, message_id }, { adrDirs,
     } catch (error) { if (!error.rpc) throw error; }
   }
 
-  const terms = questionTerms(message.pruned ? '' : message.body, task?.title || '');
+  const recorded = await relaydDecisions(call, swarm, id, signal, mismatches);
+  const terms = questionTerms(message.pruned ? '' : message.body, question.decision?.question || '', task?.title || '');
   const { adrs, notes } = await relatedDecisions(adrDirs, terms, { forbidden });
   for (const note of notes) cut.note(note);
   return cut.result({
     question, task, evidence, related_plans: related,
-    decisions: { dirs: adrDirs, terms, adrs, ...(adrs.length ? {} : { note: "No ADR mentions the question's terms." }) },
+    decisions: { relayd: recorded, dirs: adrDirs, terms, adrs, ...(adrs.length ? {} : { note: "No ADR in the project directories mentions the question's terms." }) },
     mismatches,
-    next: 'Present this dossier to the human (question, task, evidence, decisions and what does not add up) before proposing a reply. If you propose Reply, the human confirms it on a card with the exact text.',
+    next: question.decision
+      ? 'Present this dossier to the human (the structured question with its options, consequences, the agent recommendation, evidence, scope, reversibility and cost of waiting; the ADRs in force; what does not add up) and let the human choose. Then propose Decide with the option the human chose, the reply text and a decision_note with the human\'s reasons: Comal drafts the ADR and the human approves it on a card. Never pick the option yourself because the agent recommends it.'
+      : 'Present this dossier to the human (question, task, evidence, decisions and what does not add up) before proposing a reply. If you propose Reply, the human confirms it on a card with the exact text.',
   });
 }
+
+/** ADR del registro de relayd: vigentes del swarm (y de proyecto) y los que ya responden esta pregunta. */
+async function relaydDecisions(call, swarm_id, message_id, signal, mismatches) {
+  const view = item => ({ id: item.id, status: item.status, in_force: item.in_force, title: excerpt(item.title, 200), scope: item.scope, answers: item.answers ?? null, accepted_via: item.accepted_via ?? null });
+  try {
+    const [inForce, all] = await Promise.all([call('decision.list', { swarm_id, in_force: true, limit: 20 }, signal), call('decision.list', { swarm_id, limit: 200 }, signal)]);
+    const answering = (all.decisions || []).filter(item => item.answers === message_id);
+    for (const item of answering) mismatches.push(`ADR ${clean(item.id)} (${clean(item.status)}) already answers this question.`);
+    return { in_force: (inForce.decisions || []).slice(0, 20).map(view), answering: answering.slice(0, 8).map(view), open: 'plugin__open-relay__Decision {"decision_id":"adr-N"}' };
+  } catch (error) { if (!error.rpc) throw error; return { error: `${error.code}: ${excerpt(error.message, 200)}` }; }
+}