@milpa/comal 0.2.2 → 0.2.4

package/src/relay/flow.mjs

@@ -0,0 +1,886 @@
+import { readFile, stat, rm, mkdir, writeFile, chmod } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { t, registerMessages } from '../i18n/index.mjs';
+import { HubClient, hubRoot } from './hub-client.mjs';
+import { relayGit } from './git.mjs';
+import { proposalCard, trustCard, objectiveInput, startCard, planCard, questionCard, finishCard, statusCard, taskCounts, eyesText, eyesState, designText, blockedCard, criteriaCard, criteriaConfirmCard, criteriaWarnings, criteriaWaiting, escalationCard, line } from './cards.mjs';
+import { RelayClient, RelayConnection, needsHuman, RECOMMENDED_CAPS } from '../plugins/open-relay/client.mjs';
+import { approve, reject, decide, reply, ack, acceptCriteria, rejectCriteria, reopenCriteria, overrideReview, retryReview } from '../plugins/open-relay/actions.mjs';
+import { decisionBlock } from '../plugins/open-relay/decision.mjs';
+import { normalizeSwarmView, blockLabel } from '../tui/swarm-panel.mjs';
+import { swarmFinished, blockedForOperator, blockedReason } from './follow.mjs';
+import { pendingDelivery, pendingOperatorDeliveries, operatorDelivery } from '../plugins/open-relay/lookup.mjs';
+import { projectPlanCard, relayOptionLabel } from '../remote-relay.mjs';
+import { RelayDecisionBroker } from './broker.mjs';
+import { createHash } from 'node:crypto';
+
+// /relay: comando del HOST (no un plugin: los plugins no registran comandos de barra) que
+// lleva de un repo a un enjambre funcionando con tres confirmaciones humanas: la propuesta
+// del proyecto (crear y arrancar), la confianza (plugin de esta versión de Comal + delegación
+// de relayd) y el arranque (objetivo, líder, presupuesto). Después, el plan del líder, las
+// preguntas y el resultado llegan como tarjetas (follow.mjs).
+// Principio de Milpa: la autoridad es del host. Todo esto son controles humanos invisibles
+// para el modelo: no hay herramienta que cree proyectos, arranque enjambres ni apruebe. El
+// modelo sólo puede dejar un BORRADOR de objetivo (RelayDraft) que el humano ve en la
+// tarjeta de arranque.
+registerMessages({
+  'Use /relay [status|new [NAME]|start|stop|unlink|hub ROOT].': 'Usa /relay [status|new [NOMBRE]|start|stop|unlink|hub RAÍZ].',
+  '/relay needs a git repository (run Comal inside one).': '/relay necesita un repositorio git (abre Comal dentro de uno).',
+  'A /relay card is already open.': 'Ya hay una tarjeta de /relay abierta.',
+  'Starting relay-hub': 'Arrancando relay-hub',
+  'The local hub API (loopback {listen}) was not running; Comal starts it as the user unit relay-hub.': 'La API local del hub (loopback {listen}) no estaba en marcha; Comal la arranca como la unidad de usuario relay-hub.',
+  'relay-hub started ({how}) on {listen}.': 'relay-hub arrancado ({how}) en {listen}.',
+  'Reading the repo': 'Leyendo el repo',
+  'Criteria of {swarm} are already {status}.': 'Los criterios de {swarm} ya están {status}.',
+  'Success criteria v{version} accepted ({status}): the lead can plan.': 'Criterios de éxito v{version} aceptados ({status}): el líder ya puede planear.',
+  'Success criteria rejected ({status}); the reviewer got your reason.': 'Criterios de éxito rechazados ({status}); el revisor recibió tu motivo.',
+  'The review of {task} no longer waits for you.': 'La revisión de {task} ya no te espera.',
+  '{task} accepted over the reviewer ({status}).': '{task} aceptada sobre el revisor ({status}).',
+  'Why another review': 'Por qué otra revisión',
+  'Recorded in relayd as your decision (review.retry) with exactly this text; the reviewer gets a new review task.': 'Queda en relayd como tu decisión (review.retry) con exactamente este texto; el revisor recibe una tarea de revisión nueva.',
+  '{task} goes back to the reviewer ({status}).': '{task} vuelve al revisor ({status}).',
+  'Decide the success criteria of {swarm}': 'Decidir los criterios de éxito de {swarm}',
+  'Escalated review of {task}': 'Revisión escalada de {task}',
+  'See the result of {swarm}': 'Ver el resultado de {swarm}',
+  'project.detect: branch, excludes, checks and budget for this repo. Nothing is written.': 'project.detect: rama, exclusiones, checks y presupuesto de este repo. No se escribe nada.',
+  'Nothing was created.': 'No se creó nada.',
+  'Creating {name}': 'Creando {name}',
+  'relay-hub writes the project, adds the branch {branch} and starts its relayd (up to 2 min).': 'relay-hub escribe el proyecto, añade la rama {branch} y arranca su relayd (hasta 2 min).',
+  'Project {name} created and started: relayd ready, UI {web}, branch {branch}.': 'Proyecto {name} creado y arrancado: relayd listo, UI {web}, rama {branch}.',
+  'Field to edit': 'Campo a editar',
+  'Name': 'Nombre', 'Base (branch or commit)': 'Base (rama o commit)', 'Model of the agents': 'Modelo de los agentes', 'Checks': 'Checks', 'Budget per swarm': 'Presupuesto por enjambre', 'Excludes': 'Exclusiones', 'Back to the proposal': 'Volver a la propuesta',
+  'Lowercase letters, digits and dashes (up to 40). Branch relay/NAME.': 'Minúsculas, dígitos y guiones (hasta 40). Rama relay/NOMBRE.',
+  'Any ref of the repo: HEAD, origin/main, a commit…': 'Cualquier ref del repo: HEAD, origin/main, un commit…',
+  'Ollama model for comal (lead and agents).': 'Modelo de Ollama para comal (líder y agentes).',
+  'Calls, tokens and wall time, e.g. 300 30M 4h.': 'Llamadas, tokens y tiempo de pared, p. ej. 300 30M 4h.',
+  'Comma-separated globs, relative to the repo.': 'Globs separados por comas, relativos al repo.',
+  'Check {id}': 'Check {id}',
+  'Command run in the candidate (sh, from its root). Empty removes the check.': 'Comando que se ejecuta en el candidato (sh, desde su raíz). Vacío quita el check.',
+  'Add a check': 'Añadir un check',
+  'New check: id (c-…) and command, e.g. c-lint npm run lint': 'Check nuevo: id (c-…) y comando, p. ej. c-lint npm run lint',
+  'Use lowercase, digits and dashes.': 'Usa minúsculas, dígitos y guiones.',
+  'Use three values: calls tokens time (300 30M 4h).': 'Usa tres valores: llamadas tokens tiempo (300 30M 4h).',
+  'Use c-ID followed by the command.': 'Usa c-ID seguido del comando.',
+  'Connecting Comal': 'Conectando Comal',
+  'Issuing the delegate session and enabling the open-relay plugin for this repo.': 'Emitiendo la sesión delegada y activando el plugin open-relay para este repo.',
+  'Comal connected to {project}: delegation {caps} in {file}; the plugin watches the swarm (/swarm).': 'Comal conectado a {project}: delegación {caps} en {file}; el plugin vigila el enjambre (/swarm).',
+  'Project {project} is ready; Comal is not connected (trust card declined). /relay connects it later.': 'El proyecto {project} está listo; Comal no está conectado (se declinó la tarjeta de confianza). /relay lo conecta después.',
+  'The open-relay plugin did not become active: {error}': 'El plugin open-relay no quedó activo: {error}',
+  'No swarm started.': 'No se arrancó ningún enjambre.',
+  'Starting the swarm': 'Arrancando el enjambre',
+  'swarm.start in {project}: account, root grant, lead and root task.': 'swarm.start en {project}: cuenta, grant raíz, líder y tarea raíz.',
+  'Swarm {swarm} started in {project} (lead {lead}). The lead is reading the repo; its plan will show up here as a card. /swarm shows the live board.': 'Enjambre {swarm} arrancado en {project} (líder {lead}). El líder está leyendo el repo; su plan aparecerá aquí como tarjeta. /swarm muestra el tablero en vivo.',
+  'Project {project} stopped (unit {unit}: {state}). Its swarms and the branch stay; /relay starts it again.': 'Proyecto {project} parado (unidad {unit}: {state}). Sus enjambres y la rama se quedan; /relay lo vuelve a arrancar.',
+  'Starting {project}': 'Arrancando {project}',
+  'relay-hub starts its relayd and waits until it is ready.': 'relay-hub arranca su relayd y espera a que esté listo.',
+  'Project {project} started: relayd {state}, UI {web}.': 'Proyecto {project} arrancado: relayd {state}, UI {web}.',
+  'This repo is not linked to a relay-hub project. /relay proposes one.': 'Este repo no está ligado a un proyecto de relay-hub. /relay propone uno.',
+  'Unlinked {project} from this repo (the project stays in relay-hub).': 'Desligado {project} de este repo (el proyecto sigue en relay-hub).',
+  'relay-hub root saved: {root} (RELAY_HUB_ROOT still wins).': 'Raíz de relay-hub guardada: {root} (RELAY_HUB_ROOT sigue ganando).',
+  'Use /relay hub /absolute/root.': 'Usa /relay hub /raíz/absoluta.',
+  'Plan {id} is already {status}.': 'El plan {id} ya está {status}.',
+  'Reason for the lead': 'Motivo para el líder',
+  'The lead is woken up with exactly this text and proposes again.': 'El líder despierta con exactamente este texto y vuelve a proponer.',
+  'Plan {id} approved ({status}): relayd applied {steps} steps; the swarm is working.': 'Plan {id} aprobado ({status}): relayd aplicó {steps} pasos; el enjambre está trabajando.',
+  'Plan {id} rejected ({status}); the lead got your reason.': 'Plan {id} rechazado ({status}); el líder recibió tu motivo.',
+  'Note for the ADR (optional)': 'Nota para el ADR (opcional)',
+  'Why you choose «{option}». Enter with nothing skips it; it goes into the ADR decision.': 'Por qué eliges «{option}». Enter vacío la omite; va a la decisión del ADR.',
+  'Chosen option: «{option}».': 'Opción elegida: «{option}».',
+  'Decision recorded as {adr} and sent to {to}.': 'Decisión registrada como {adr} y enviada a {to}.',
+  'Your answer': 'Tu respuesta',
+  'Exact text sent to {to} (msg.reply).': 'Texto exacto que recibe {to} (msg.reply).',
+  'Answer sent to {to} ({status}).': 'Respuesta enviada a {to} ({status}).',
+  'Message marked as read.': 'Mensaje dado por leído.',
+  'Diff of {branch} ({count} more lines not shown; git diff {base}..{branch})': 'Diff de {branch} ({count} líneas más sin mostrar; git diff {base}..{branch})',
+  'The model drafted a swarm objective; /relay shows it on the start card (nothing was started).': 'El modelo redactó un objetivo de enjambre; /relay lo muestra en la tarjeta de arranque (no se arrancó nada).',
+  'not linked': 'sin ligar',
+  'relayd is stopped': 'relayd está parado',
+  'no delegation yet': 'todavía sin delegación',
+  'the open-relay plugin watches another project': 'el plugin open-relay vigila otro proyecto',
+  'the open-relay plugin is {state}': 'el plugin open-relay está {state}',
+  'relayd rejected the delegation ({code})': 'relayd rechazó la delegación ({code})',
+  'Comal version changed: the trust is asked again for this version': 'Cambió la versión de Comal: la confianza se pide de nuevo para esta versión',
+  'Design file': 'Archivo del diseño',
+  'Path of a local image (PNG or JPEG). relay-hub copies it to design/ and the agents read it in `_relay/design/`. Nothing is started.': 'Ruta de una imagen local (PNG o JPEG). relay-hub la copia a design/ y los agentes la leen en `_relay/design/`. No se arranca nada.',
+  'Design attached: {file} ({size}) · the lead and the agents read it in `{mirror}`.': 'Diseño adjuntado: {file} ({size}) · el líder y los agentes lo leen en `{mirror}`.',
+  'Design: {file} ({size}) · the lead and the agents read it in `{mirror}`': 'Diseño: {file} ({size}) · el líder y los agentes lo leen en `{mirror}`',
+  'The hub could not attach the design: {error}': 'El hub no pudo adjuntar el diseño: {error}',
+  'Browser check (c-web)': 'Check de navegador (c-web)',
+  'Add a browser check (c-web)': 'Añadir un check de navegador (c-web)',
+  'Page of the browser check (c-web)': 'Página del check de navegador (c-web)',
+  'Path of the page in the project, e.g. / or /pricing.': 'Ruta de la página en el proyecto, p. ej. / o /precios.',
+  'Selector of the browser check (c-web)': 'Selector del check de navegador (c-web)',
+  'CSS selector the page must show, e.g. #greeting': 'Selector CSS que la página debe mostrar, p. ej. #greeting',
+  'Use a path that starts with / (e.g. / or /pricing).': 'Usa una ruta que empiece por / (p. ej. / o /precios).',
+  'Use a selector without spaces (e.g. #greeting).': 'Usa un selector sin espacios (p. ej. #greeting).',
+  'browser check (chrome-lab over ssh)': 'check de navegador (chrome-lab por ssh)',
+  'Plan {id} changed since it was shown (another digest); review it again.': 'El plan {id} cambió desde que se mostró (otro digest); revísalo de nuevo.',
+  'The question {id} is no longer waiting for an answer.': 'La pregunta {id} ya no espera respuesta.',
+  'The success criteria of {swarm} changed since they were shown; review them again.': 'Los criterios de éxito de {swarm} cambiaron desde que se mostraron; revísalos de nuevo.',
+  'This card is being answered from the browser right now; /relay shows it again.': 'Esta tarjeta se está respondiendo ahora mismo desde el navegador; /relay la vuelve a mostrar.',
+  'Blocked task {task}': 'Tarea bloqueada {task}',
+  'Retry it yourself in your terminal, exactly: {command}': 'Reinténtala tú en tu terminal, exactamente: {command}',
+});
+
+const NAME = /^[a-z][a-z0-9-]{0,39}$/;
+const sha256 = value => createHash('sha256').update(value).digest('hex');
+const shellWord = value => /^[A-Za-z0-9_./:=@%+-]+$/.test(value) ? value : `'${String(value).replace(/'/g, `'\\''`)}'`;
+// Resultado de apply* que es una decisión aplicada en relayd (el resto: obsoleta o ya decidida).
+const APPLIED = new Set(['approved', 'rejected', 'decided', 'answered', 'acked']);
+/** Campos de la fila del libro cuando decide el navegador (/rc): origen, sesión, request_id y resultado. */
+const remoteRow = (remote, outcome) => remote?.source === 'remote_browser' ? { source: remote.source, remote_session: remote.remote_session, remote_request_id: remote.remote_request_id, card_id: remote.card_id, remote_state: 'applied', remote_outcome: outcome } : {};
+const CHECK = /^c-[a-z0-9][a-z0-9-]{0,30}$/;
+/** Parte del presupuesto del swarm para el revisor (open-relay gate 6: el 30 % no daba para
+ *  dos rondas de corrección y la revisión final). */
+export const REVIEW_SHARE_PCT = 40;
+const webUrl = value => value ? (/^https?:\/\//.test(value) ? value : `http://${value}`) : null;
+const exists = async file => { try { await stat(file); return true; } catch { return false; } };
+const samePath = (a, b) => path.resolve(String(a || '')) === path.resolve(String(b || ''));
+const amount = text => { const match = /^(\d+(?:[.,]\d+)?)\s*([kKmMgG]?)$/.exec(text); if (!match) return null; const value = Number(match[1].replace(',', '.')) * ({ k: 1e3, m: 1e6, g: 1e9 }[match[2].toLowerCase()] || 1); return Number.isFinite(value) && value > 0 ? Math.round(value) : null; };
+const duration = text => { const match = /^(\d+(?:[.,]\d+)?)\s*(h|m|min|s)?$/i.exec(text); if (!match) return null; const value = Number(match[1].replace(',', '.')) * ({ h: 3600e3, m: 60e3, min: 60e3, s: 1e3 }[String(match[2] || 'h').toLowerCase()]); return Number.isFinite(value) && value > 0 ? Math.round(value) : null; };
+/** «300 30M 4h» → presupuesto del hub. */
+export function parseBudget(text) {
+  const parts = String(text || '').trim().split(/[\s,·/]+/).filter(Boolean).filter(part => !/^(calls?|llamadas?|tokens?)$/i.test(part));
+  if (parts.length !== 3) return null;
+  const calls = amount(parts[0]), tokens = amount(parts[1]), wall = duration(parts[2]);
+  return calls && tokens && wall ? { calls, tokens, wall_time_ms: wall } : null;
+}
+/** Script de un check a partir de una línea de comando (mismo encabezado que los del hub). */
+export function checkScript(id, command) {
+  return `#!/bin/sh\n# Editado en Comal (/relay). El candidato (solo lectura) está en $RELAY_CANDIDATE;\n# las rutas de la tarea, una por línea, en $RELAY_TASK_PATHS. exit 0 = PASS.\nset -eu\nC="\${RELAY_CANDIDATE:?}"\n# ${id}: ${command.replace(/\n/g, ' ')}\ncd "$C"\n${command}\necho "PASS: ${id}"\n`;
+}
+
+// Check de navegador del proyecto (`c-web`): su `browser` lleva la página y el selector y lo
+// corre el runner de navegador del hub (chrome-lab por ssh), no la shell. El script que se
+// escribe falla en cerrado para que nadie lo confunda con una comprobación sin navegador.
+const WEB_CHECK = 'c-web';
+const isBrowserCheck = check => check?.id === WEB_CHECK || Boolean(check?.browser);
+/** Página y selector de un check de navegador: `browser.page/selector` o la descripción «/ #greeting». */
+const browserTarget = check => {
+  const browser = check?.browser && typeof check.browser === 'object' ? check.browser : {};
+  const match = /(\/\S*)\s+(#\S+)/.exec(String(check?.description || ''));
+  return { page: browser.page || match?.[1] || '/', selector: browser.selector || match?.[2] || '' };
+};
+const browserCheck = ({ page, selector }, current) => {
+  const id = current?.id || WEB_CHECK;
+  return {
+    ...current, id, browser: { page, selector },
+    description: `${page} ${selector} · ${t('browser check (chrome-lab over ssh)')}`,
+    script: current?.script || checkScript(id, `echo '${id}: lo comprueba el runner de navegador del hub (chrome-lab por ssh); mira browser.page y browser.selector' >&2; exit 1`),
+  };
+};
+/** ¿Hay ojos? Mismo criterio que cards.eyesText: sin estado o con un estado de «ninguno», no. */
+const eyesAvailable = eyes => Boolean(eyes) && !['', 'none', 'absent', 'missing', 'off', 'disabled'].includes(eyesState(eyes));
+
+export class RelayFlow {
+  constructor({ cwd, ui, state, plugins, env = process.env, version, pluginCode, hubFactory = options => new HubClient(options), delegateFactory = options => new RelayClient(options), connect = options => new RelayConnection(options), git = relayGit, record = async () => {}, execFileFn = execFile, signal, broker = new RelayDecisionBroker() }) {
+    Object.assign(this, { cwd, ui, state, plugins, env, version, pluginCode, hubFactory, delegateFactory, connect, git, record, execFileFn, signal, broker });
+    this.busy = false; this.draft = null; this.current = null; this.clients = new Map(); this.view = null;
+  }
+  /** Última foto del panel /swarm (la del plugin open-relay); la tarjeta de estado la usa. */
+  setView(view) { this.view = normalizeSwarmView(view); }
+  /** Borrador del modelo (RelayDraft): sólo texto para la tarjeta de arranque, nunca arranca nada. */
+  setDraft(objective) { this.draft = { objective: String(objective).slice(0, 4000), at: Date.now() }; this.ui?.notice?.(t('The model drafted a swarm objective; /relay shows it on the start card (nothing was started).')); }
+  async repo() { try { return await this.git.toplevel(this.cwd); } catch { throw Object.assign(new Error(t('/relay needs a git repository (run Comal inside one).')), { code: 'RELAY_NO_REPO' }); } }
+  async hub() { return this.hubFactory({ root: hubRoot({ env: this.env, saved: await this.state.hubRoot() }).root, env: this.env }); }
+  /** Proyecto ligado a este repo (para el seguimiento por tarjetas), sin tocar el hub. */
+  async init() { try { const repo = await this.repo(), link = await this.state.link(repo); this.current = link ? { repo, ...link } : null; } catch { this.current = null; } return this.current; }
+  controlDir(hub, project) { return path.join(hub.root, 'projects', project, 'ctl'); }
+  /** Cliente delegado del HOST para las decisiones de las tarjetas (mismo token que el plugin). */
+  client(project, root) {
+    const key = `${root}/${project}`;
+    if (!this.clients.has(key)) { const controlDir = path.join(root, 'projects', project, 'ctl'); this.clients.set(key, this.delegateFactory({ controlDir, tokenFile: path.join(controlDir, 'comal.token') })); }
+    return this.clients.get(key);
+  }
+  close() { for (const client of this.clients.values()) client.close?.(); this.clients.clear(); }
+
+  /** /relay en la TUI. Devuelve el texto que queda en la conversación (o ''). */
+  async run(arg = '') {
+    if (this.busy) throw new Error(t('A /relay card is already open.'));
+    this.busy = true;
+    try { return await this.#dispatch(String(arg).trim()); }
+    finally { this.busy = false; if (this.ui.setup?.kind === 'status') this.ui.clearSetup(); }
+  }
+  async #dispatch(arg) {
+    const [sub = '', ...rest] = arg.split(/\s+/).filter(Boolean);
+    if (sub === 'hub') {
+      const root = rest.join(' ').trim();
+      if (!root || !path.isAbsolute(root.replace(/^~(?=\/|$)/, os.homedir()))) throw new Error(t('Use /relay hub /absolute/root.'));
+      const resolved = path.resolve(root.replace(/^~(?=\/|$)/, os.homedir()));
+      await this.state.setHubRoot(resolved); return t('relay-hub root saved: {root} (RELAY_HUB_ROOT still wins).', { root: resolved });
+    }
+    if (!['', 'status', 'new', 'start', 'stop', 'unlink'].includes(sub) || (sub !== 'new' && rest.length) || rest.length > 1) throw new Error(t('Use /relay [status|new [NAME]|start|stop|unlink|hub ROOT].'));
+    const repo = await this.repo();
+    if (sub === 'unlink') { const link = await this.state.link(repo); if (!link) return t('This repo is not linked to a relay-hub project. /relay proposes one.'); await this.state.unlink(repo); this.current = null; return t('Unlinked {project} from this repo (the project stays in relay-hub).', { project: link.project }); }
+    const hub = await this.#ensureHub();
+    if (sub === 'new') return this.#propose(repo, hub, { name: rest[0] });
+    const link = await this.#link(repo, hub);
+    if (!link) { if (sub === 'stop' || sub === 'start') return t('This repo is not linked to a relay-hub project. /relay proposes one.'); return this.#propose(repo, hub, {}); }
+    if (sub === 'stop') return this.#stop(hub, link.project);
+    if (sub === 'start') return this.#start(hub, link.project);
+    return this.#status(repo, hub, link);
+  }
+  /** -p: estado como JSON (sin tarjetas: arrancar o decidir es de la TUI). */
+  async text() {
+    const repo = await this.repo(), hub = await this.hub(), link = await this.state.link(repo), health = await hub.ready();
+    const out = { repo, hub: { root: hub.root, running: Boolean(health), version: health?.version || null }, link: link || null };
+    if (health && link) out.project = await hub.call('project.status', { project: link.project }).catch(error => ({ error: { code: error.code, message: error.message } }));
+    return JSON.stringify(out, null, 2);
+  }
+  async #ensureHub() {
+    const hub = await this.hub();
+    if (await hub.ready({ signal: this.signal })) return hub;
+    const listen = await hub.listen();
+    this.ui.setupStatus({ title: t('Starting relay-hub'), description: t('The local hub API (loopback {listen}) was not running; Comal starts it as the user unit relay-hub.', { listen }) });
+    const started = await hub.ensure({ signal: this.signal });
+    this.ui.clearSetup();
+    if (started.started) { this.ui.notice(t('relay-hub started ({how}) on {listen}.', { how: started.unit ? `systemd --user ${started.unit}` : `pid ${started.pid}`, listen })); await this.record({ action: 'hub.start', root: hub.root, listen, unit: started.unit || null }); }
+    return hub;
+  }
+  /** Proyecto ligado y todavía presente en el hub (si no, el vínculo se olvida). */
+  async #link(repo, hub) {
+    const link = await this.state.link(repo);
+    if (!link) { this.current = null; return null; }
+    const { projects = [] } = await hub.call('project.list', {}, { signal: this.signal });
+    if (!projects.some(item => item.name === link.project)) { await this.state.unlink(repo); this.current = null; return null; }
+    this.current = { repo, ...link }; return this.current;
+  }
+  async #projectFile(hub, project) { try { return JSON.parse(await readFile(path.join(hub.root, 'projects', project, 'project.json'), 'utf8'))?.proposal || null; } catch { return null; } }
+
+  // ── 1. Propuesta ──────────────────────────────────────────────────────────
+  async #detect(hub, repo, edits) {
+    this.ui.setupStatus({ title: t('Reading the repo'), description: t('project.detect: branch, excludes, checks and budget for this repo. Nothing is written.') });
+    try {
+      const proposal = await hub.call('project.detect', { repo, ...(edits.name ? { name: edits.name } : {}), ...(edits.base ? { base: edits.base } : {}) }, { signal: this.signal });
+      if (edits.model) proposal.runtimes = (proposal.runtimes || []).map(item => ({ ...item, model: edits.model }));
+      if (edits.budget) proposal.budget = edits.budget;
+      if (edits.excludes) proposal.excludes = edits.excludes;
+      if (edits.checks) proposal.checks = edits.checks;
+      return proposal;
+    } finally { this.ui.clearSetup(); }
+  }
+  async #propose(repo, hub, { name }) {
+    const edits = { name: name || undefined };
+    let { projects = [] } = await hub.call('project.list', {}, { signal: this.signal });
+    let proposal = await this.#detect(hub, repo, edits);
+    // Nombre libre por omisión: el del directorio, y si ya existe, NOMBRE-2, NOMBRE-3…
+    if (!name && projects.some(item => item.name === proposal.name)) {
+      for (let n = 2; n < 100; n++) { const candidate = `${proposal.name}`.slice(0, 36) + `-${n}`; if (!projects.some(item => item.name === candidate)) { edits.name = candidate; break; } }
+      proposal = await this.#detect(hub, repo, edits);
+    }
+    const existing = projects.filter(item => item.repo && samePath(item.repo, repo));
+    for (;;) {
+      const choice = await this.ui.setupChoice({ ...proposalCard({ proposal, existing, repoLabel: path.basename(repo) }), signal: this.signal });
+      if (!choice || choice === 'cancel') return t('Nothing was created.');
+      if (choice === 'edit') { proposal = await this.#edit(hub, repo, proposal, edits); continue; }
+      if (choice.startsWith('existing:')) {
+        const project = choice.slice('existing:'.length), info = await this.#projectFile(hub, project);
+        await this.state.setLink(repo, { project, hub_root: hub.root, branch: info?.branch || `relay/${project}`, base_commit: info?.base_commit || null });
+        this.current = { repo, ...(await this.state.link(repo)) };
+        await this.record({ action: 'project.link', project });
+        const status = await hub.call('project.status', { project }, { signal: this.signal });
+        if (status.unit?.active !== 'active') await this.#start(hub, project, { quiet: true });
+        return this.#connectAndStart(hub, project, info);
+      }
+      break;
+    }
+    this.ui.setupStatus({ title: t('Creating {name}', { name: proposal.name }), description: t('relay-hub writes the project, adds the branch {branch} and starts its relayd (up to 2 min).', { branch: proposal.branch }) });
+    let started;
+    try {
+      const created = await hub.call('project.create', { proposal }, { signal: this.signal });
+      await this.record({ action: 'project.create', project: proposal.name, repo, branch: proposal.branch, base: proposal.base || 'HEAD', base_commit: proposal.base_commit, checks: (proposal.checks || []).map(check => check.id), branch_created: created?.branch_created ?? null });
+      await this.state.setLink(repo, { project: proposal.name, hub_root: hub.root, branch: proposal.branch, base_commit: proposal.base_commit });
+      this.current = { repo, ...(await this.state.link(repo)) };
+      started = await hub.call('project.start', { project: proposal.name }, { signal: this.signal, timeoutMs: 180000 });
+      await this.record({ action: 'project.start', project: proposal.name, active: started?.active ?? null });
+    } finally { this.ui.clearSetup(); }
+    this.ui.notice(t('Project {name} created and started: relayd ready, UI {web}, branch {branch}.', { name: proposal.name, web: webUrl(started?.web) || `http://127.0.0.1:${proposal.port}`, branch: proposal.branch }));
+    return this.#connectAndStart(hub, proposal.name, proposal);
+  }
+  async #edit(hub, repo, proposal, edits) {
+    // Check de navegador del proyecto: si viene (c-web) se edita su página y su selector; con
+    // ojos disponibles y sin él, la misma entrada lo añade a proposal.checks.
+    const web = (proposal.checks || []).find(isBrowserCheck), target = browserTarget(web), eyes = eyesAvailable(proposal.eyes);
+    const field = await this.ui.setupChoice({ title: t('Field to edit'), items: [
+      { id: 'name', label: t('Name'), description: proposal.name }, { id: 'base', label: t('Base (branch or commit)'), description: `${proposal.base || 'HEAD'} (${String(proposal.base_commit || '').slice(0, 8)})` },
+      { id: 'model', label: t('Model of the agents'), description: proposal.runtimes?.[0]?.model || '' }, { id: 'checks', label: t('Checks'), description: (proposal.checks || []).map(check => check.id).join(', ') },
+      { id: 'budget', label: t('Budget per swarm'), description: `${proposal.budget?.calls} ${proposal.budget?.tokens} ${Math.round((proposal.budget?.wall_time_ms || 0) / 60000)}min` },
+      { id: 'excludes', label: t('Excludes'), description: (proposal.excludes || []).slice(0, 4).join(', ') },
+      ...(web || eyes ? [{ id: 'web', label: t(web ? 'Browser check (c-web)' : 'Add a browser check (c-web)'), description: web ? `${target.page} ${target.selector}`.trim() : eyesText(proposal.eyes) }] : []),
+      { id: 'back', label: t('Back to the proposal') },
+    ], signal: this.signal });
+    const ask = (title, description, value, validate) => this.ui.setupInput({ title, description, value, validate, signal: this.signal });
+    if (field === 'name') { const value = await ask(t('Name'), t('Lowercase letters, digits and dashes (up to 40). Branch relay/NAME.'), proposal.name, text => NAME.test(text.trim()) || t('Use lowercase, digits and dashes.')); if (value) { edits.name = value.trim(); return this.#detect(hub, repo, edits); } }
+    if (field === 'base') { const value = await ask(t('Base (branch or commit)'), t('Any ref of the repo: HEAD, origin/main, a commit…'), proposal.base || 'HEAD'); if (value?.trim()) { edits.base = value.trim(); return this.#detect(hub, repo, edits); } }
+    if (field === 'model') { const value = await ask(t('Model of the agents'), t('Ollama model for comal (lead and agents).'), proposal.runtimes?.[0]?.model || ''); if (value?.trim()) { edits.model = value.trim(); proposal.runtimes = (proposal.runtimes || []).map(item => ({ ...item, model: edits.model })); } }
+    if (field === 'budget') { const value = await ask(t('Budget per swarm'), t('Calls, tokens and wall time, e.g. 300 30M 4h.'), `${proposal.budget?.calls} ${proposal.budget?.tokens} ${Math.round((proposal.budget?.wall_time_ms || 0) / 3600000) || 4}h`, text => Boolean(parseBudget(text)) || t('Use three values: calls tokens time (300 30M 4h).')); if (value) { edits.budget = parseBudget(value); proposal.budget = edits.budget; } }
+    if (field === 'excludes') { const value = await ask(t('Excludes'), t('Comma-separated globs, relative to the repo.'), (proposal.excludes || []).join(', ')); if (value !== null && value !== undefined) { edits.excludes = value.split(',').map(item => item.trim()).filter(Boolean); proposal.excludes = edits.excludes; } }
+    if (field === 'checks') {
+      const checks = [...(proposal.checks || [])];
+      const pick = await this.ui.setupChoice({ title: t('Checks'), items: [...checks.map(check => ({ id: `check:${check.id}`, label: check.id, description: line(String(check.description || '').replace(/`/g, ''), 120) })), { id: 'add', label: t('Add a check') }, { id: 'back', label: t('Back to the proposal') }], signal: this.signal });
+      if (pick?.startsWith('check:')) {
+        const id = pick.slice(6), value = await ask(t('Check {id}', { id }), t('Command run in the candidate (sh, from its root). Empty removes the check.'), '');
+        if (value !== null && value !== undefined) { edits.checks = value.trim() ? checks.map(check => check.id === id ? { ...check, description: `\`${value.trim()}\` (${t('Checks').toLowerCase()} /relay)`, script: checkScript(id, value.trim()) } : check) : checks.filter(check => check.id !== id); proposal.checks = edits.checks; }
+      } else if (pick === 'add') {
+        const value = await ask(t('Add a check'), t('New check: id (c-…) and command, e.g. c-lint npm run lint'), 'c-', text => { const [id, ...command] = text.trim().split(/\s+/); return (CHECK.test(id) && command.length > 0 && !checks.some(check => check.id === id)) || t('Use c-ID followed by the command.'); });
+        if (value) { const [id, ...command] = value.trim().split(/\s+/); edits.checks = [...checks, { id, description: `\`${command.join(' ')}\` (/relay)`, script: checkScript(id, command.join(' ')), timeout_ms: 600000 }]; proposal.checks = edits.checks; }
+      }
+    }
+    if (field === 'web') {
+      const page = await ask(t('Page of the browser check (c-web)'), t('Path of the page in the project, e.g. / or /pricing.'), target.page || '/', text => /^\/[^\s'"]*$/.test(text.trim()) || t('Use a path that starts with / (e.g. / or /pricing).'));
+      if (page?.trim()) {
+        const selector = await ask(t('Selector of the browser check (c-web)'), t('CSS selector the page must show, e.g. #greeting'), target.selector || '', text => /^[^\s'"]+$/.test(text.trim()) || t('Use a selector without spaces (e.g. #greeting).'));
+        if (selector?.trim()) {
+          const check = browserCheck({ page: page.trim(), selector: selector.trim() }, web);
+          edits.checks = web ? (proposal.checks || []).map(item => item === web ? check : item) : [...(proposal.checks || []), check];
+          proposal.checks = edits.checks;
+        }
+      }
+    }
+    return proposal;
+  }
+
+  // ── 2. Confianza ──────────────────────────────────────────────────────────
+  /** ¿Comal ya opera este proyecto? {ok, principal, caps} o {ok:false, reason, reissue}. */
+  async connection(hub, project) {
+    const controlDir = this.controlDir(hub, project), tokenFile = path.join(controlDir, 'comal.token');
+    const desc = await this.plugins.describe('open-relay');
+    const watching = desc.configured && desc.config?.controlDir === controlDir;
+    if (!await exists(tokenFile)) return { ok: false, reason: t('no delegation yet') };
+    let hello = null, reissue = null;
+    const connection = this.connect({ controlDir, tokenFile });
+    try { hello = (await connection.open(this.signal))?.delegate || null; }
+    catch (error) { if (needsHuman(error)) reissue = t('relayd rejected the delegation ({code})', { code: error.code }); }
+    finally { connection.close?.(); }
+    if (reissue) return { ok: false, reason: reissue, reissue };
+    if (!watching) return { ok: false, reason: desc.configured ? t('the open-relay plugin watches another project') : t('not linked'), ...hello };
+    if (desc.trust?.status === 'stale' && desc.trust.reasons?.some(reason => /package|fingerprint/.test(reason))) return { ok: false, reason: t('Comal version changed: the trust is asked again for this version'), ...hello };
+    if (desc.state !== 'active' || desc.trust?.status !== 'trusted' || desc.config?.notify !== 'cards') return { ok: false, reason: t('the open-relay plugin is {state}', { state: desc.state || desc.trust?.status || '?' }), ...hello };
+    return { ok: true, principal: hello?.principal, caps: hello?.caps || [] };
+  }
+  async #trust(hub, project) {
+    const state = await this.connection(hub, project);
+    if (state.ok) return true;
+    const controlDir = this.controlDir(hub, project), tokenFile = path.join(controlDir, 'comal.token'), code = await this.pluginCode();
+    const choice = await this.ui.setupChoice({ ...trustCard({ project, controlDir, tokenFile, version: this.version, pkg: code?.package || null, fingerprint: code?.code_fingerprint, reissue: state.reissue }), signal: this.signal });
+    if (choice !== 'trust') return false;
+    this.ui.setupStatus({ title: t('Connecting Comal'), description: t('Issuing the delegate session and enabling the open-relay plugin for this repo.') });
+    try {
+      const issued = await this.#delegate(hub, project, { replace: Boolean(state.reissue) });
+      await this.plugins.link('open-relay', { controlDir, tokenFile, notify: 'cards' }, { signal: this.signal });
+      const desc = await this.plugins.describe('open-relay');
+      if (desc.state !== 'active') throw new Error(t('The open-relay plugin did not become active: {error}', { error: desc.error || desc.state || '?' }));
+      await this.record({ action: 'relay.trust', project, control_dir: controlDir, token_file: tokenFile, caps: RECOMMENDED_CAPS.split(','), issued: issued.issued !== false, comal_version: this.version, package_integrity: code?.package?.integrity || null, code_fingerprint: code?.code_fingerprint || null });
+      this.clients.get(`${hub.root}/${project}`)?.close?.(); this.clients.delete(`${hub.root}/${project}`);
+      this.ui.notice(t('Comal connected to {project}: delegation {caps} in {file}; the plugin watches the swarm (/swarm).', { project, caps: RECOMMENDED_CAPS, file: tokenFile }));
+      return true;
+    } finally { this.ui.clearSetup(); }
+  }
+  /** Delegación por el hub (project.delegate); con un hub sin ese método, la CLI relay. */
+  async #delegate(hub, project, { replace }) {
+    try { return await hub.call('project.delegate', { project, client: 'comal', caps: RECOMMENDED_CAPS.split(','), ...(replace ? { replace: true } : {}) }, { signal: this.signal }); }
+    catch (error) { if (error.code !== 'method_not_found') throw error; }
+    const config = await hub.config(), controlDir = this.controlDir(hub, project), tokenFile = path.join(controlDir, 'comal.token');
+    const bin = path.join(config.bin_dir || path.join(config.open_relay || '', 'target', 'release'), 'relay');
+    if (replace) await rm(tokenFile, { force: true });
+    else if (await exists(tokenFile)) return { token_file: tokenFile, issued: false };
+    const principal = (() => { try { return os.userInfo().username || 'operator'; } catch { return 'operator'; } })();
+    await new Promise((resolve, reject) => this.execFileFn(bin, ['--control-dir', controlDir, 'session', 'issue-delegate', '--principal', principal, '--client', 'comal', '--caps', RECOMMENDED_CAPS, '--ttl', '30d', '--out', tokenFile], { timeout: 30000 }, (error, _out, stderr) => error ? reject(new Error(`relay session issue-delegate: ${String(stderr || error.message).trim().slice(0, 400)}`)) : resolve()));
+    return { token_file: tokenFile, issued: true };
+  }
+
+  // ── 3. Arranque ───────────────────────────────────────────────────────────
+  async #connectAndStart(hub, project, info) {
+    if (!await this.#trust(hub, project)) return t('Project {project} is ready; Comal is not connected (trust card declined). /relay connects it later.', { project });
+    return this.#newSwarm(hub, project, info);
+  }
+  /** ¿El hub de este proyecto admite project.attach? Es de open-relay 2.12. Sin sondas: manda lo
+   *  que declara project.detect (`attach` o 'project.attach' en sus métodos/capacidades) y, si
+   *  no dice nada, la versión que publica /v1/health (hub.ready().version). Sin señal: no. */
+  async #canAttachDesign(hub, info) {
+    const declared = info?.attach ?? info?.project?.attach;
+    if (typeof declared === 'boolean') return declared;
+    const methods = [...(info?.methods || []), ...(info?.capabilities || [])].map(String);
+    if (methods.length) return methods.includes('project.attach');
+    try {
+      const health = await hub.ready({ signal: this.signal });
+      const [major, minor] = String(health?.version || '').split('.').map(part => Number.parseInt(part, 10));
+      return Number.isInteger(major) && (major > 2 || (major === 2 && minor >= 12));
+    } catch { return false; }
+  }
+  /** Adjunta el diseño al proyecto ANTES de swarm.start: relay-hub copia la imagen al repo y la
+   *  espeja en _relay/design/ para que el líder y los agentes la lean. Queda fila en el libro. */
+  async #attachDesign(hub, project, file) {
+    try {
+      const result = await hub.call('project.attach', { project, file }, { signal: this.signal, timeoutMs: 120000 });
+      const shown = result?.design || result || {}, name = path.basename(String(shown.name || shown.file || file));
+      const design = { name, width: shown.width ?? null, height: shown.height ?? null, bytes: shown.bytes ?? shown.size ?? null };
+      await this.record({ action: 'project.attach', project, file, design: `design/${name}`, mirror: `_relay/design/${name}`, width: design.width, height: design.height, bytes: design.bytes });
+      this.ui.notice(t('Design attached: {file} ({size}) · the lead and the agents read it in `{mirror}`.', designText(design)));
+      return design;
+    } catch (error) {
+      this.ui.notice(t('The hub could not attach the design: {error}', { error: line(error.message, 200) }));
+      return null;
+    }
+  }
+  async #newSwarm(hub, project, info) {
+    info ||= await this.#projectFile(hub, project) || {};
+    const lead = { runtime: info.runtimes?.[0]?.runtime || 'comal', model: info.runtimes?.[0]?.model || '?' }, branch = info.branch || `relay/${project}`;
+    const budget = info.budget || { calls: 300, tokens: 30000000, wall_time_ms: 14400000 };
+    let objective = this.draft?.objective || '', drafted = Boolean(objective), design = info.design || null, withReview = false;
+    // project.attach llega con open-relay 2.12: se pregunta al hub por su capacidad, nunca se
+    // prueba el método a ciegas (un method_not_found dejaría ruido en el log del hub).
+    const canAttachDesign = await this.#canAttachDesign(hub, info);
+    const write = value => this.ui.setupInput({ ...objectiveInput({ project, lead: `${lead.runtime} · ${lead.model}` }), value, signal: this.signal });
+    for (;;) {
+      if (!objective.trim()) { const value = await write(''); if (!value?.trim()) return t('No swarm started.'); objective = value.trim(); drafted = false; }
+      // Revisor (open-relay F8): con ojos en el proyecto se ofrece arrancar con revisor.
+      const eyes = info.eyes?.host || info.remote_hosts?.[0] || null;
+      // El reparto que muestra la tarjeta es el que se pide (share_pct): no depende del valor
+      // por omisión del hub (open-relay v2.29: 40 %, antes 30 %).
+      const reviewer = eyes ? { runtime: lead.runtime, model: lead.model, eyes, share: REVIEW_SHARE_PCT } : null;
+      const choice = await this.ui.setupChoice({ ...startCard({ project, objective, lead, budget, branch, drafted, design, canAttachDesign, reviewer }), signal: this.signal });
+      if (choice === 'design') {
+        const file = await this.ui.setupInput({ title: t('Design file'), description: t('Path of a local image (PNG or JPEG). relay-hub copies it to design/ and the agents read it in `_relay/design/`. Nothing is started.'), signal: this.signal });
+        if (file?.trim()) { const attached = await this.#attachDesign(hub, project, file.trim()); if (attached) design = attached; }
+        continue;
+      }
+      if (choice === 'edit') { const value = await write(objective); if (value?.trim()) { objective = value.trim(); drafted = false; } continue; }
+      if (choice !== 'start' && choice !== 'start-review') return t('No swarm started.');
+      withReview = choice === 'start-review';
+      break;
+    }
+    // El objetivo que ve el líder cita el diseño: es su referencia visual (nadie la compara solo).
+    const designLine = design ? t('Design: {file} ({size}) · the lead and the agents read it in `{mirror}`', designText(design)) : null;
+    const brief = designLine ? `${objective}\n\n${designLine}` : objective;
+    this.ui.setupStatus({ title: t('Starting the swarm'), description: t('swarm.start in {project}: account, root grant, lead and root task.', { project }) });
+    let started;
+    try { started = await hub.call('swarm.start', { project, objective: brief, ...(withReview ? { review: { share_pct: REVIEW_SHARE_PCT } } : {}) }, { signal: this.signal }); }
+    finally { this.ui.clearSetup(); }
+    const swarm = started?.swarm?.swarm_id || started?.swarm?.swarm || '?';
+    this.draft = null;
+    const link = this.current?.project === project ? this.current : null;
+    await this.state.setSwarm(project, swarm, { objective: brief, started_at: new Date().toISOString(), base_commit: link?.base_commit || info.base_commit || null, branch });
+    await this.record({ action: 'swarm.start', project, swarm, review: withReview, objective: brief, lead: `${lead.runtime}:${started?.swarm?.lead_model || lead.model}`, budget: started?.swarm?.budget || budget, outcome: started?.swarm?.outcome || null, drafted_by_model: drafted, design: design ? `design/${design.name}` : null });
+    return t('Swarm {swarm} started in {project} (lead {lead}). The lead is reading the repo; its plan will show up here as a card. /swarm shows the live board.', { swarm, project, lead: `${lead.runtime} · ${started?.swarm?.lead_model || lead.model}` });
+  }
+
+  // ── Estado, parar, arrancar ───────────────────────────────────────────────
+  async #status(repo, hub, link) {
+    const project = link.project, status = await hub.call('project.status', { project }, { signal: this.signal });
+    const connected = status.unit?.active === 'active' ? await this.connection(hub, project) : { ok: false, reason: t('relayd is stopped') };
+    const watching = connected.ok && this.view?.available;
+    const swarms = watching ? this.view.swarms : (status.swarms || []).map(item => ({ id: item.id, objective: item.objective, tasks: [], pending: [], plans: [] }));
+    const pending = [];
+    if (watching) for (const swarm of this.view.swarms) {
+      if (criteriaWaiting(swarm.criteria) && swarm.criteria.digest) pending.push({ id: `criteria|${swarm.id}|${swarm.criteria.digest}`, label: t('Decide the success criteria of {swarm}', { swarm: swarm.id }), description: `v${swarm.criteria.version} · ${swarm.criteria.status}` });
+      // open-relay v2.31: criterios aceptados se pueden reabrir a medio swarm (criteria.reopen).
+      if (swarm.criteria?.status === 'accepted' && swarm.criteria.digest) pending.push({ id: `reopen|${swarm.id}|${swarm.criteria.digest}`, label: t('Reopen the success criteria of {swarm}', { swarm: swarm.id }), description: `v${swarm.criteria.version} · ${swarm.criteria.status}` });
+      for (const task of swarm.tasks || []) if (task.state === 'needs_attention' && task.review_kind) pending.push({ id: `escalation|${swarm.id}|${task.id}`, label: t('Escalated review of {task}', { task: task.id }), description: line(task.title || '', 120) });
+      for (const plan of swarm.plans || []) if (plan.proposal_id) pending.push({ id: `plan|${swarm.id}|${plan.proposal_id}`, label: t('Review the plan {id}', { id: plan.proposal_id }), description: line(plan.summary || '', 120) });
+      for (const item of swarm.pending || []) if (item.kind === 'question' && item.message_id) pending.push({ id: `question|${swarm.id}|${item.message_id}`, label: t('Answer {from}', { from: item.from }), description: line(item.decision?.question || item.excerpt || '', 120) });
+      for (const task of swarm.tasks || []) if (blockedForOperator(task)) pending.push({ id: `blocked|${swarm.id}|${task.id}`, label: t('Blocked task {task}', { task: task.id }), description: line([blockLabel(task.state), task.title].filter(Boolean).join(' · '), 120) });
+      // El final que el seguimiento aún no pudo enseñar (pantalla ocupada) también se ofrece aquí.
+      if (swarmFinished(swarm)) { const tracked = await this.state.swarm(project, swarm.id); if (tracked && !tracked.finished_at) pending.push({ id: `finish|${swarm.id}|`, label: t('See the result of {swarm}', { swarm: swarm.id }), description: line(tracked.objective || swarm.objective || '', 120) }); }
+    }
+    const choice = await this.ui.setupChoice({ ...statusCard({ project, status, connected, swarms, pending }), signal: this.signal });
+    if (!choice || choice === 'close') return '';
+    if (choice === 'swarm') return this.#newSwarm(hub, project, null);
+    if (choice === 'board') { this.ui.toggleSwarm?.(); return ''; }
+    if (choice === 'trust') return await this.#trust(hub, project) ? this.#newSwarm(hub, project, null) : t('Project {project} is ready; Comal is not connected (trust card declined). /relay connects it later.', { project });
+    if (choice === 'stop') return this.#stop(hub, project);
+    if (choice === 'start') return this.#start(hub, project);
+    if (choice === 'new') return this.#propose(repo, hub, {});
+    const [kind, swarm, id] = choice.split('|');
+    if (kind === 'plan') await this.planDecision({ project, root: hub.root, swarm, proposal_id: id });
+    if (kind === 'question') await this.questionDecision({ project, root: hub.root, swarm, message_id: id });
+    if (kind === 'criteria') await this.criteriaDecision({ project, root: hub.root, swarm, digest: id });
+    if (kind === 'reopen') await this.reopenCriteria({ project, root: hub.root, swarm, digest: id });
+    if (kind === 'escalation') await this.escalationDecision({ project, root: hub.root, swarm, task: { id } });
+    if (kind === 'blocked') { const task = this.view?.swarms.find(item => item.id === swarm)?.tasks.find(item => item.id === id); if (task) await this.blockedDecision({ project, root: hub.root, swarm, task }); }
+    if (kind === 'finish') { const view = this.view.swarms.find(item => item.id === swarm); if (view) await this.finishDecision({ project, root: hub.root, swarm, view, repo }); }
+    return '';
+  }
+  async #stop(hub, project) {
+    const result = await hub.call('project.stop', { project }, { signal: this.signal });
+    await this.record({ action: 'project.stop', project, active: result?.active ?? null });
+    return t('Project {project} stopped (unit {unit}: {state}). Its swarms and the branch stay; /relay starts it again.', { project, unit: result?.unit || `open-relay-${project}`, state: result?.active || '?' });
+  }
+  async #start(hub, project, { quiet = false } = {}) {
+    this.ui.setupStatus({ title: t('Starting {project}', { project }), description: t('relay-hub starts its relayd and waits until it is ready.') });
+    let result; try { result = await hub.call('project.start', { project }, { signal: this.signal, timeoutMs: 180000 }); } finally { this.ui.clearSetup(); }
+    await this.record({ action: 'project.start', project, active: result?.active ?? null });
+    const text = t('Project {project} started: relayd {state}, UI {web}.', { project, state: result?.daemon?.state || result?.active || '?', web: webUrl(result?.web) || '?' });
+    if (quiet) this.ui.notice(text);
+    return text;
+  }
+
+  // ── Tarjetas del seguimiento (follow.mjs) ─────────────────────────────────
+  #calls(project, root) {
+    const client = this.client(project, root);
+    return { client, call: (method, params, signal) => client.call(method, params, { signal }), mutate: (method, params, signal) => client.mutate(method, params, { signal }) };
+  }
+  // ── Una tarjeta, dos superficies (broker.mjs) ─────────────────────────────
+  // Presentar (TUI) y aplicar (TUI o navegador) van separados: apply* vuelve a leer relayd justo
+  // antes de mutar, muta con las mismas funciones y claves, y deja la fila del libro. La TUI toma
+  // el candado del broker al CONFIRMAR; si el navegador decide antes, su tarjeta se cierra sola.
+  /** ¿Ya se decidió desde el navegador? Lo dice y no vuelve a enseñar la tarjeta. */
+  #elsewhere(key) {
+    const decided = this.broker.outcome(key);
+    if (decided?.by !== 'browser') return false;
+    this.ui.notice(t('Already decided from the browser ({outcome}); nothing was sent.', { outcome: t(decided.outcome) }));
+    return true;
+  }
+  /** Confirmación en la TUI: candado → apply → commit (o suelta el candado si no se aplicó). */
+  async #confirm(key, apply, done) {
+    const lock = this.broker.begin(key, 'terminal');
+    if (!lock.ok) {
+      if (lock.decided) { this.#elsewhere(key); return 'decided'; }
+      this.ui.notice(t('This card is being answered from the browser right now; /relay shows it again.')); return 'later';
+    }
+    let result;
+    try { result = await apply(); } catch (error) { this.broker.release(key); throw error; }
+    if (APPLIED.has(result?.outcome)) { this.broker.commit(key, { outcome: result.outcome, by: 'terminal' }); done(result); return 'decided'; }
+    this.broker.release(key);
+    return done(result) || 'later';
+  }
+
+  /** Tarjeta del plan: datos de plan.get justo antes de mostrarla; se aprueba ese digest. */
+  async planDecision({ project, root, swarm, proposal_id }) {
+    const key = `plan:${swarm}:${proposal_id}`;
+    if (this.#elsewhere(key)) return 'decided';
+    const card = this.broker.open(key, this.signal);
+    try {
+      const { call } = this.#calls(project, root);
+      const got = await call('plan.get', { proposal_id }, card.signal);
+      if (got?.proposal?.status && got.proposal.status !== 'pending') { this.ui.notice(t('Plan {id} is already {status}.', { id: proposal_id, status: got.proposal.status })); return 'decided'; }
+      // Cómo se comprueba cada tarea: la descripción de los checks del proyecto (project.json del hub).
+      const checks = (await this.#projectFile({ root }, project))?.checks || [];
+      const choice = await this.ui.setupChoice({ ...planCard({ got, checks }), signal: card.signal });
+      if (this.#elsewhere(key)) return 'decided';
+      const digest = got.proposal.digest, apply = extra => () => this.applyPlan({ project, root, swarm, proposal_id, digest, ...extra });
+      const done = result => {
+        if (result.outcome === 'approved') this.ui.notice(t('Plan {id} approved ({status}): relayd applied {steps} steps; the swarm is working.', { id: proposal_id, status: result.status, steps: result.steps ?? 0 }));
+        else if (result.outcome === 'rejected') this.ui.notice(t('Plan {id} rejected ({status}); the lead got your reason.', { id: proposal_id, status: result.status }));
+        else if (result.outcome === 'already_decided') { this.ui.notice(t('Plan {id} is already {status}.', { id: proposal_id, status: result.status || '?' })); return 'decided'; }
+        else this.ui.notice(t('Plan {id} changed since it was shown (another digest); review it again.', { id: proposal_id }));
+      };
+      if (choice === 'approve') return await this.#confirm(key, apply({ choice: 'approve' }), done);
+      if (choice === 'reject') {
+        const reason = await this.ui.setupInput({ title: t('Reason for the lead'), description: t('The lead is woken up with exactly this text and proposes again.'), signal: card.signal });
+        if (this.#elsewhere(key)) return 'decided';
+        if (!reason?.trim()) return 'later';
+        return await this.#confirm(key, apply({ choice: 'reject', reason: reason.trim() }), done);
+      }
+      return 'later';
+    } catch (error) { if (this.#elsewhere(key)) return 'decided'; throw error; }
+    finally { card.close(); }
+  }
+  /**
+   * Aplica una decisión sobre un plan (TUI o navegador). Re-lee plan.get justo antes de mutar:
+   * sólo con status pending y el MISMO digest (relayd admite rechazar un plan ya aprobado y aún
+   * no aplicado). Desde el navegador además el sha256 de la proyección que vio debe coincidir.
+   * → { outcome: approved | rejected | already_decided | not_pending | digest | projection }.
+   */
+  async applyPlan({ project, root, swarm, proposal_id, digest, choice, reason = '', projection = null, signal = this.signal, ...remote }) {
+    const { call, mutate } = this.#calls(project, root);
+    const got = await call('plan.get', { proposal_id }, signal), status = got?.proposal?.status;
+    if (status !== 'pending') return { outcome: ['approved', 'applied', 'rejected'].includes(status) ? 'already_decided' : 'not_pending', status };
+    if (got.proposal.digest !== digest) return { outcome: 'digest', status };
+    if (projection !== null) {
+      const checks = (await this.#projectFile({ root }, project))?.checks || [];
+      if (projectPlanCard({ project, swarm, got, checks }).card.body.projection_sha256 !== projection) return { outcome: 'projection', status };
+    }
+    if (choice === 'approve') {
+      const result = await approve(mutate, { proposal_id, digest }, signal);
+      await this.record({ action: 'plan.approve', project, swarm, proposal_id, digest, status: result.status, outcome: result.outcome, idempotency_key: result.idempotency_key, ...remoteRow(remote, 'approved') });
+      await this.#settlePlanNotices(call, mutate, swarm, proposal_id);
+      return { outcome: 'approved', status: result.status, steps: result.steps?.length ?? 0 };
+    }
+    if (choice !== 'reject' || !String(reason).trim()) return { outcome: 'invalid' };
+    // D10: relayd (v2.31) rechaza solo si la propuesta sigue `pending`; si otro operador la aprobó
+    // entre la re-lectura de arriba y aquí, es un conflicto sin efectos.
+    const expected_status = 'pending';
+    const result = await reject(mutate, { proposal_id, reason: String(reason).trim(), expected_status }, signal);
+    await this.record({ action: 'plan.reject', project, swarm, proposal_id, reason: String(reason).trim(), status: result.status, idempotency_key: result.idempotency_key, ...remoteRow(remote, 'rejected') });
+    await this.#settlePlanNotices(call, mutate, swarm, proposal_id);
+    return { outcome: 'rejected', status: result.status };
+  }
+  /** Revisor (open-relay F7): criterios de éxito que esperan al humano (criteria.get justo antes
+   *  de mostrarlos). Se acepta el digest que se ve; rechazar despierta al revisor con el motivo. */
+  async criteriaDecision({ project, root, swarm }) {
+    const { call } = this.#calls(project, root);
+    const got = await call('criteria.get', { swarm_id: swarm }, this.signal);
+    if (!criteriaWaiting(got) || !got?.current?.digest) { this.ui.notice(t('Criteria of {swarm} are already {status}.', { swarm, status: got?.status || '?' })); return 'decided'; }
+    const digest = got.current.digest, key = `criteria:${swarm}:${digest}`;
+    if (this.#elsewhere(key)) return 'decided';
+    const card = this.broker.open(key, this.signal);
+    try {
+      const choice = await this.ui.setupChoice({ ...criteriaCard({ got, swarm }), signal: card.signal });
+      if (this.#elsewhere(key)) return 'decided';
+      const done = result => {
+        if (result.outcome === 'approved') this.ui.notice(t('Success criteria v{version} accepted ({status}): the lead can plan.', { version: got.current.version, status: result.status }));
+        else if (result.outcome === 'rejected') this.ui.notice(t('Success criteria rejected ({status}); the reviewer got your reason.', { status: result.status }));
+        else if (result.outcome === 'already_decided') { this.ui.notice(t('Criteria of {swarm} are already {status}.', { swarm, status: result.status || '?' })); return 'decided'; }
+        else this.ui.notice(t('The success criteria of {swarm} changed since they were shown; review them again.', { swarm }));
+      };
+      if (choice === 'accept') {
+        // open-relay v2.33: con avisos, aceptar se confirma aparte (por omisión, volver).
+        const warnings = criteriaWarnings(got.current.items, { checked: got.basis_checked === true });
+        if (warnings.size) {
+          const sure = await this.ui.setupChoice({ ...criteriaConfirmCard({ got, swarm, warnings }), signal: card.signal });
+          if (this.#elsewhere(key)) return 'decided';
+          if (sure !== 'accept') return 'later';
+        }
+        return await this.#confirm(key, () => this.applyCriteria({ project, root, swarm, digest, choice: 'accept' }), done);
+      }
+      if (choice === 'reject') {
+        const reason = await this.ui.setupInput({ title: t('Reason for the reviewer'), description: t('The reviewer is woken up with exactly this text and proposes again.'), signal: card.signal });
+        if (this.#elsewhere(key)) return 'decided';
+        if (!reason?.trim()) return 'later';
+        return await this.#confirm(key, () => this.applyCriteria({ project, root, swarm, digest, choice: 'reject', reason: reason.trim() }), done);
+      }
+      return 'later';
+    } catch (error) { if (this.#elsewhere(key)) return 'decided'; throw error; }
+    finally { card.close(); }
+  }
+  /** open-relay v2.31: reabrir los criterios aceptados a medio swarm (criteria.reopen, solo desde
+   *  la terminal). La versión aceptada sigue vigente hasta que el humano acepte la que proponga el
+   *  revisor; el motivo le llega tal cual. */
+  async reopenCriteria({ project, root, swarm, digest }) {
+    const { call, mutate } = this.#calls(project, root);
+    const got = await call('criteria.get', { swarm_id: swarm }, this.signal);
+    if (got?.status !== 'accepted' || got?.current?.digest !== digest) { this.ui.notice(t('Criteria of {swarm} are already {status}.', { swarm, status: got?.status || '?' })); return 'decided'; }
+    const reason = await this.ui.setupInput({ title: t('Why reopen the criteria'), description: t('The reviewer is woken up with exactly this text and proposes a new version; v{version} stays in force until you accept the new one.', { version: got.current.version }), signal: this.signal });
+    if (!reason?.trim()) return 'later';
+    const result = await reopenCriteria(mutate, { swarm_id: swarm, digest, reason: reason.trim() }, this.signal);
+    await this.record({ action: 'criteria.reopen', project, swarm, digest, version: got.current.version, reason: reason.trim(), status: result.status, idempotency_key: result.idempotency_key });
+    this.ui.notice(t('Success criteria of {swarm} reopened ({status}); the reviewer got your reason.', { swarm, status: result.status }));
+    return 'decided';
+  }
+  /** Aplica una decisión sobre los criterios (TUI o navegador): criteria.get justo antes, mismo digest. */
+  async applyCriteria({ project, root, swarm, digest, choice, reason = '', signal = this.signal, ...remote }) {
+    const { call, mutate } = this.#calls(project, root);
+    const got = await call('criteria.get', { swarm_id: swarm }, signal);
+    if (!criteriaWaiting(got)) return { outcome: ['accepted', 'rejected'].includes(got?.status) ? 'already_decided' : 'not_pending', status: got?.status };
+    if (got?.current?.digest !== digest) return { outcome: 'digest', status: got?.status };
+    if (choice === 'accept') {
+      const result = await acceptCriteria(mutate, { swarm_id: swarm, digest }, signal);
+      await this.record({ action: 'criteria.accept', project, swarm, digest, version: got.current.version, status: result.status, idempotency_key: result.idempotency_key, ...remoteRow(remote, 'approved') });
+      return { outcome: 'approved', status: result.status, version: got.current.version };
+    }
+    if (choice !== 'reject' || !String(reason).trim()) return { outcome: 'invalid' };
+    const result = await rejectCriteria(mutate, { swarm_id: swarm, digest, reason: String(reason).trim() }, signal);
+    await this.record({ action: 'criteria.reject', project, swarm, digest, reason: String(reason).trim(), status: result.status, idempotency_key: result.idempotency_key, ...remoteRow(remote, 'rejected') });
+    return { outcome: 'rejected', status: result.status };
+  }
+  /** Revisor (open-relay F7): revisión escalada (rondas agotadas o sin veredicto). Aceptar sobre
+   *  el revisor es review.override y otra revisión del mismo candidato review.retry (gate 3),
+   *  ambos con el motivo del humano; cancelar o revisar sigue en su CLI. */
+  async escalationDecision({ project, root, swarm, task: brief }) {
+    const { call, mutate } = this.#calls(project, root);
+    const got = await call('task.get', { task_id: brief?.id }, this.signal), task = got?.task || got;
+    if (task?.state !== 'needs_attention' || !task?.review?.pending) { this.ui.notice(t('The review of {task} no longer waits for you.', { task: line(brief?.id || '?', 60) })); return 'decided'; }
+    const choice = await this.ui.setupChoice({ ...escalationCard({ task }), signal: this.signal });
+    if (choice === 'retry') {
+      const why = await this.ui.setupInput({ title: t('Why another review'), description: t('Recorded in relayd as your decision (review.retry) with exactly this text; the reviewer gets a new review task.'), signal: this.signal });
+      if (!why?.trim()) return 'later';
+      const retried = await retryReview(mutate, { task_id: task.id, reason: why.trim() }, this.signal);
+      await this.record({ action: 'review.retry', project, swarm, task: task.id, reason: why.trim(), status: retried.status, idempotency_key: retried.idempotency_key });
+      this.ui.notice(t('{task} goes back to the reviewer ({status}).', { task: line(task.id, 60), status: retried.status }));
+      return 'decided';
+    }
+    if (choice !== 'override') return 'later';
+    const reason = await this.ui.setupInput({ title: t('Why you accept over the reviewer'), description: t('Recorded in relayd as your decision (review.override) with exactly this text.'), signal: this.signal });
+    if (!reason?.trim()) return 'later';
+    const result = await overrideReview(mutate, { task_id: task.id, reason: reason.trim() }, this.signal);
+    await this.record({ action: 'review.override', project, swarm, task: task.id, reason: reason.trim(), status: result.status, idempotency_key: result.idempotency_key });
+    this.ui.notice(t('{task} accepted over the reviewer ({status}).', { task: line(task.id, 60), status: result.status }));
+    return 'decided';
+  }
+  // relayd avisa al operador de cada plan con informes (`msg-<propuesta>-proposed` y, con
+  // revisor, sólo `msg-<propuesta>-reviewed`). Decidido el plan ya están atendidos. relayd
+  // (gate 5) los da por leídos él mismo al aprobar o rechazar; uno más viejo no. Sólo se
+  // confirman las entregas del operador que el buzón aún muestra pendientes, por su
+  // delivery_id: nunca un id de mensaje ni uno que no existe (relayd respondería
+  // UNAUTHORIZED, «entrega no encontrada o sin acceso»). Mejor esfuerzo: un fallo no se
+  // muestra como error de la decisión, que ya se aplicó.
+  async #settlePlanNotices(call, mutate, swarm, proposal_id) {
+    try {
+      const wanted = ['proposed', 'reviewed'].map(suffix => operatorDelivery(`msg-${proposal_id}-${suffix}`));
+      for (const delivery_id of await pendingOperatorDeliveries(call, swarm, wanted, this.signal)) {
+        try { await ack(mutate, { delivery_id }, this.signal); } catch {}
+      }
+    } catch {}
+  }
+  /** Tarjeta de una pregunta: opciones (→ ADR con Decide) o texto libre (Reply). */
+  async questionDecision({ project, root, swarm, message_id, task }) {
+    const key = `question:${swarm}:${message_id}`;
+    if (this.#elsewhere(key)) return 'decided';
+    const card = this.broker.open(key, this.signal);
+    try {
+      const { call } = this.#calls(project, root);
+      const message = await call('msg.get', { message_id }, card.signal), block = decisionBlock(message);
+      const choice = await this.ui.setupChoice({ ...questionCard({ message, block, task }), signal: card.signal });
+      if (this.#elsewhere(key)) return 'decided';
+      const done = result => {
+        if (result.outcome === 'decided') this.ui.notice(t('Decision recorded as {adr} and sent to {to}.', { adr: result.adr || '?', to: result.to }));
+        else if (result.outcome === 'answered') this.ui.notice(t('Answer sent to {to} ({status}).', { to: result.to, status: result.status }));
+        else if (result.outcome === 'acked') this.ui.notice(t('Message marked as read.'));
+        else this.ui.notice(t('The question {id} is no longer waiting for an answer.', { id: message_id }));
+      };
+      if (choice?.startsWith('option:') && block) {
+        const index = Number(choice.slice(7)), option = block.options[index]?.label; if (!option) return 'later';
+        const note = await this.ui.setupInput({ title: t('Note for the ADR (optional)'), description: t('Why you choose «{option}». Enter with nothing skips it; it goes into the ADR decision.', { option }), signal: card.signal });
+        if (this.#elsewhere(key)) return 'decided';
+        if (note === null || note === undefined) return 'later';
+        return await this.#confirm(key, () => this.applyQuestion({ project, root, swarm, message_id, mode: 'option', option_index: index, text: note }), done);
+      }
+      if (choice === 'reply') {
+        const to = message?.from?.role ? `role ${line(message.from.role, 60)}` : line(message?.from?.kind || '?', 40);
+        const body = await this.ui.setupInput({ title: t('Your answer'), description: t('Exact text sent to {to} (msg.reply).', { to }), signal: card.signal });
+        if (this.#elsewhere(key)) return 'decided';
+        if (!body?.trim()) return 'later';
+        return await this.#confirm(key, () => this.applyQuestion({ project, root, swarm, message_id, mode: 'reply', text: body }), done);
+      }
+      if (choice === 'ack') return await this.#confirm(key, () => this.applyQuestion({ project, root, swarm, message_id, mode: 'ack' }), done);
+      return 'later';
+    } catch (error) { if (this.#elsewhere(key)) return 'decided'; throw error; }
+    finally { card.close(); }
+  }
+  /**
+   * Aplica una respuesta a una pregunta (TUI o navegador) con las funciones de la tarjeta: opción
+   * → ADR (decide: propose → record → reply → ack), texto → msg.reply, o msg.ack. Desde el
+   * navegador además la entrega debe seguir pendiente en el buzón del operador y la opción debe
+   * ser la que vio (sha256 de su etiqueta proyectada). El ADR lo redacta el host, nunca el navegador.
+   */
+  async applyQuestion({ project, root, swarm, message_id, mode, option_index = null, option_label_sha256 = null, text = '', signal = this.signal, ...remote }) {
+    const { call, mutate } = this.#calls(project, root);
+    const message = await call('msg.get', { message_id }, signal), block = decisionBlock(message);
+    if (remote.source === 'remote_browser' && !(await pendingDelivery(call, message?.swarm || swarm, message_id, signal))) return { outcome: 'not_pending' };
+    const to = message?.from?.role ? `role ${line(message.from.role, 60)}` : line(message?.from?.kind || '?', 40);
+    if (mode === 'option') {
+      const chosen = block?.options?.[option_index];
+      if (!chosen || (option_label_sha256 !== null && sha256(relayOptionLabel(chosen.label)) !== option_label_sha256)) return { outcome: 'option' };
+      const option = chosen.label, note = String(text || '').trim();
+      const body = t('Chosen option: «{option}».', { option }) + (note ? `\n${note}` : '');
+      const result = await decide(call, mutate, { message_id, option, body, ...(note ? { decision_note: note } : {}), ack: true }, signal);
+      await this.record({ action: 'decision.record', project, swarm, message_id, option, decision_id: result.decision?.id, adr_digest: result.decision?.adr_digest, status: result.status, ...remoteRow(remote, 'decided') });
+      return { outcome: 'decided', adr: result.decision?.id, to, status: result.status };
+    }
+    if (mode === 'reply') {
+      const body = String(text || '').trim(); if (!body) return { outcome: 'invalid' };
+      const result = await reply(call, mutate, { message_id, body, ack: true }, signal);
+      await this.record({ action: 'msg.reply', project, swarm, message_id, status: result.status, body_sha256: result.sent?.body_sha256, ...remoteRow(remote, 'answered') });
+      return { outcome: 'answered', to, status: result.status };
+    }
+    if (mode === 'ack') {
+      await ack(mutate, { message_id }, signal);
+      await this.record({ action: 'msg.ack', project, swarm, message_id, ...remoteRow(remote, 'acked') });
+      return { outcome: 'acked', to };
+    }
+    return { outcome: 'invalid' };
+  }
+  /** Evidencia del verificador para las tareas `done` con un criterio que es un check de navegador
+   *  del proyecto (`browser` en project.json). Lee `attestation.list` por cada operación de la tarea
+   *  con la sesión delegada (capacidad read) y guarda la captura 0600 en la caché del humano para
+   *  que la compare con el diseño. Sólo metadatos: la tarjeta nunca lleva píxeles. */
+  async #evidence({ root, project, swarm, tasks = [] }) {
+    if (!root) return [];
+    const checks = (await this.#projectFile({ root }, project))?.checks || [];
+    const web = new Set(checks.filter(check => isBrowserCheck(check)).map(check => String(check?.id || '')).filter(Boolean));
+    if (!web.size) return [];
+    const { call } = this.#calls(project, root), out = [];
+    const idsOf = value => (Array.isArray(value) ? value : []).map(item => typeof item === 'string' ? item : item?.id).filter(Boolean);
+    for (const task of tasks.filter(item => item.state === 'done' && item.id)) {
+      let got = null;
+      try { got = await call('task.get', { task_id: task.id }, this.signal); } catch { continue; }
+      const criteria = idsOf(got?.task?.criteria || task.criteria).filter(id => web.has(id));
+      if (!criteria.length) continue;
+      const operations = got?.task?.operations || got?.operations || [];
+      for (const operation of operations) {
+        const operationId = operation?.id || operation?.operation_id;
+        if (!operationId) continue;
+        let list; try { list = await call('attestation.list', { operation_id: operationId }, this.signal); } catch { continue; }
+        for (const item of (Array.isArray(list) ? list : list?.attestations || list?.items || [])) {
+          const check = String(item?.check || item?.criterion || item?.criterion_id || criteria[0]);
+          if (!web.has(check)) continue;
+          const outcome = String(item?.outcome || item?.result || 'PASS');
+          const capture = item?.capture && typeof item.capture === 'object' ? item.capture : {};
+          const saved = await this.#saveCapture({ project, swarm, task: task.id, check, capture, name: capture.name || item?.capture_name || `${task.id}.png` });
+          out.push({ task: task.id, check, outcome, ...(saved ? { capture: saved } : {}) });
+        }
+      }
+    }
+    return out;
+  }
+  /** `review` de la tarea raíz del líder (task.get) si pasó por la revisión final; si no, null. */
+  async #finalReview({ root, project, tasks = [] }) {
+    const rootTask = tasks.find(task => /^t-root/.test(task.id || '') && task.state === 'done');
+    if (!rootTask || !root) return null;
+    try { const got = await this.#calls(project, root).call('task.get', { task_id: rootTask.id }, this.signal); return (got?.task || got)?.review || null; } catch { return null; }
+  }
+  /** Guarda la captura del verificador en $XDG_CACHE_HOME/comal/relay-evidence/<proyecto>/<enjambre>/
+   *  con permisos 0600 (fuera del candidato: es del humano). Devuelve {bytes, path} o null. */
+  async #saveCapture({ project, swarm, task, check, capture, name }) {
+    const file = path.basename(String(name || `${task}.png`)).replace(/[^\w.-]/g, '_') || `${task}.png`;
+    const data = capture?.data ?? capture?.base64 ?? capture?.content_base64 ?? capture?.content ?? null;
+    let bytes = null;
+    try {
+      if (typeof data === 'string' && data) bytes = Buffer.from(data.replace(/^data:[^,]*,/, ''), 'base64');
+      else if (data instanceof Uint8Array) bytes = Buffer.from(data);
+      else if (capture?.path || capture?.file) bytes = await readFile(String(capture.path || capture.file));
+    } catch { return null; }
+    if (!bytes?.length) return null;
+    const cache = this.env?.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+    const dir = path.join(cache, 'comal', 'relay-evidence', project, swarm);
+    try {
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      const target = path.join(dir, file);
+      await writeFile(target, bytes, { mode: 0o600 }); await chmod(target, 0o600);
+      await this.record({ action: 'evidence.save', project, swarm, task, check, bytes: bytes.length, path: target });
+      return { bytes: bytes.length, path: target };
+    } catch { return null; }
+  }
+  /** Tarjeta de una tarea bloqueada que espera al operador (el verificador no pudo correr el check,
+   *  configuración, entorno, presupuesto, reintentos de infraestructura agotados). task.resume
+   *  NUNCA es delegable en open-relay (methods.rs: NEVER) y no está en la lista blanca del cliente
+   *  delegado: «Reintentar» enseña el comando exacto para la terminal del humano y no llama a
+   *  nada. Sin motivo, se lee de task.get (infra.last_cause / last_reason). */
+  async blockedDecision({ project, root, swarm, task, reason, check, at }) {
+    const hubRoot = root || this.current?.hub_root, { call } = this.#calls(project, hubRoot);
+    let detail = task;
+    if (!reason && task?.id) { try { const got = await call('task.get', { task_id: task.id }, this.signal); detail = { ...task, ...(got?.task || got || {}), state: task.state || got?.task?.state }; reason = blockedReason(detail, task.state); } catch { if (task.wake_cap === true) reason = blockedReason(task, task.state); } }
+    const id = line(task?.id || '?', 60), controlDir = path.join(hubRoot || '.', 'projects', project, 'ctl');
+    const command = `relay --control-dir ${shellWord(controlDir)} task resume ${shellWord(String(task?.id || '?'))}`;
+    const why = String(detail?.state || '').startsWith('blocked') || detail?.state === 'needs_attention' ? blockLabel(detail.state) : null;
+    const choice = await this.ui.setupChoice({ ...blockedCard({ task: detail, reason, check, at: at ?? task?.since, why, retry: { command } }), signal: this.signal });
+    if (choice !== 'retry') return 'later';
+    this.ui.notice(t('Retry it yourself in your terminal, exactly: {command}', { command }));
+    await this.record({ action: 'blocked.shown', project, swarm, task: task?.id || null, check: check || null, reason: line(reason || '', 200) });
+    return 'decided';
+  }
+  /** Tarjeta final: resumen, cambios de la rama (git, sólo lectura) y la fusión como decisión humana. */
+  async finishDecision({ project, swarm, view, repo, root }) {
+    const info = await this.state.swarm(project, swarm) || {}, link = this.current?.project === project ? this.current : {};
+    const branch = info.branch || link.branch || `relay/${project}`;
+    let base = info.base_commit || link.base_commit;
+    try { if (!base) base = await this.git.mergeBase(repo, 'HEAD', branch); } catch {}
+    let stat = ''; try { stat = base ? await this.git.diffStat(repo, base, branch) : ''; } catch (error) { stat = error.message; }
+    const tasks = view?.tasks || [], counts = taskCounts(tasks), ok = tasks.some(task => task.state === 'done' && /^role-int/.test(task.role || '')) || tasks.some(task => /^t-root/.test(task.id) && task.state === 'done');
+    // Ojos del verificador: sólo metadatos (tarea, check, PASS, KiB y dónde quedó la captura).
+    const evidence = await this.#evidence({ root: root || this.current?.hub_root, project, swarm, tasks });
+    // Revisor (open-relay F5/F7): veredicto final de la raíz y su evidencia (metadatos).
+    const review = await this.#finalReview({ root: root || this.current?.hub_root, project, tasks });
+    await this.state.setSwarm(project, swarm, { finished_at: new Date().toISOString() });
+    await this.record({ action: 'swarm.finished', project, swarm, branch, base_commit: base || null, counts, ok, evidence: evidence.length });
+    const choice = await this.ui.setupChoice({ ...finishCard({ swarm, objective: info.objective || view?.objective, branch, counts, diffStat: stat, base: base || '?', ok, evidence, review }), signal: this.signal });
+    if (choice === 'diff' && base) {
+      const diff = await this.git.diff(repo, base, branch);
+      this.ui.commandResult?.('relay', 'diff', (diff.truncated ? t('Diff of {branch} ({count} more lines not shown; git diff {base}..{branch})', { branch, count: diff.truncated, base: base.slice(0, 8) }) + '\n\n' : '') + diff.text);
+    }
+    return 'decided';
+  }
+}