@milpa/comal 0.2.2 → 0.2.3

package/src/relay/follow.mjs

@@ -0,0 +1,119 @@
+import { t, registerMessages } from '../i18n/index.mjs';
+import { normalizeSwarmView } from '../tui/swarm-panel.mjs';
+import { criteriaWaiting } from './cards.mjs';
+
+// Seguimiento de /relay: con el plugin open-relay en modo `notify=cards`, lo que espera al
+// humano en el proyecto ligado (planes del líder, preguntas del enjambre) y el final de los
+// enjambres que arrancó desde Comal o que se vieron vivos al seguir el proyecto (arrancados
+// por CLI u otra sesión) se presentan como TARJETAS del host, no como avisos al modelo.
+// Los datos llegan de la misma foto que alimenta /swarm (events.wait, sin sondeo); la
+// tarjeta vuelve a leer relayd justo antes de mostrarse. Una tarjeta sale sólo cuando la
+// pantalla está libre (sin otra tarjeta, permiso ni superposición modal); Esc la deja para
+// después y /relay la vuelve a ofrecer.
+registerMessages({
+  '{what} is waiting for you: /relay shows it again.': '{what} te espera: /relay lo vuelve a mostrar.',
+  'A plan': 'Un plan', 'A question from the swarm': 'Una pregunta del enjambre', 'The swarm result': 'El resultado del enjambre',
+  'The success criteria': 'Los criterios de éxito', 'An escalated review': 'Una revisión escalada', 'A blocked task': 'Una tarea bloqueada',
+  '/relay card failed: {error}': 'La tarjeta de /relay falló: {error}',
+  'wake cap reached (policy.max_wakes): its wait is over and it does not wake on its own': 'tope de despertares agotado (policy.max_wakes): su espera ya terminó y no se despierta sola',
+});
+
+const TERMINAL = new Set(['done', 'failed', 'cancelled']);
+// Criterios que esperan la decisión del humano: respaldados por el líder o escalados.
+const DECIDERS = { plan: 'planDecision', question: 'questionDecision', finish: 'finishDecision', criteria: 'criteriaDecision', escalation: 'escalationDecision', blocked: 'blockedDecision' };
+const WAITING = { plan: 'A plan', question: 'A question from the swarm', finish: 'The swarm result', criteria: 'The success criteria', escalation: 'An escalated review', blocked: 'A blocked task' };
+// Bloqueos que esperan al operador (no se resuelven solos): configuración, entorno, presupuesto
+// o reintentos de infraestructura agotados. Los demás (pregunta, aprobación, dependencia,
+// subtareas, criterios, revisión, capacidad libre) ya tienen su tarjeta o avanzan solos.
+const OPERATOR_BLOCKS = new Set(['blocked:config', 'blocked:environment', 'blocked:budget']);
+// relayd (gate OR-6): `wake_cap` es una tarea aparcada por encima de policy.max_wakes cuya
+// espera ya se resolvió: el scheduler no la despierta, sólo el operador (task resume).
+export const blockedForOperator = task => OPERATOR_BLOCKS.has(task?.state) || (String(task?.state || '').startsWith('blocked') && (task?.infra_exhausted === true || task?.wake_cap === true));
+/** Un episodio de bloqueo por tarjeta: otro bloqueo de la misma tarea (otro `since`) es otra tarjeta. */
+export const blockedKey = (swarm, task) => `blocked:${swarm}:${task.id}:${task.since || ''}`;
+/** Motivo de un bloqueo según relayd (task.get): causa y motivo de infraestructura, exactos. */
+export const blockedReason = (task, state) => (task?.wake_cap === true ? t('wake cap reached (policy.max_wakes): its wait is over and it does not wake on its own') : null) || [task?.infra?.last_cause, task?.infra?.last_reason].filter(Boolean).join(': ') || String(state || task?.state || '').split(':')[1] || null;
+const isRoot = task => /^t-root/.test(task.id || '');
+/** ¿Terminó el enjambre? Nada espera al humano, toda subtarea cerró y el líder acabó o se integró. */
+export function swarmFinished(swarm) {
+  const tasks = swarm?.tasks || [];
+  if (!tasks.length || (swarm.plans || []).length || (swarm.pending || []).some(item => item.kind === 'question')) return false;
+  const children = tasks.filter(task => !isRoot(task)), roots = tasks.filter(isRoot);
+  if (!children.length || !children.every(task => TERMINAL.has(task.state))) return false;
+  // Con revisor (open-relay F5) el final es la raíz cerrada tras su veredicto: sin el atajo de
+  // «alguna integración done», aunque la tarea del revisor ya no esté abierta.
+  const reviewed = tasks.some(task => /^t-review/.test(task.id || '') || /^role-review/.test(task.role || ''));
+  const integrated = !reviewed && children.some(task => task.state === 'done' && /^role-int/.test(task.role || ''));
+  return roots.every(task => TERMINAL.has(task.state)) || integrated;
+}
+
+/** Enjambres del proyecto ligado que se siguen aunque no se arrancaran desde Comal (CLI, otra
+ *  sesión, otra máquina): el primero que se ve VIVO (con tareas y sin terminar) queda en el estado
+ *  de /relay como si se hubiera arrancado aquí, así su final sale como tarjeta una sola vez. Uno que
+ *  ya había terminado cuando se vio por primera vez no se adopta: sin tarjetas de enjambres viejos. */
+export async function adoptLiveSwarms(state, view, current) {
+  if (!state?.setSwarm || !view?.available || !current?.project) return [];
+  const adopted = [];
+  for (const swarm of view.swarms || []) {
+    if (!swarm?.id || !(swarm.tasks || []).length || swarmFinished(swarm)) continue;
+    if (await state.swarm(current.project, swarm.id)) continue;
+    await state.setSwarm(current.project, swarm.id, { objective: swarm.objective || null, adopted_at: new Date().toISOString(), base_commit: current.base_commit || null, branch: current.branch || null });
+    adopted.push(swarm.id);
+  }
+  return adopted;
+}
+
+export class RelayFollower {
+  constructor({ flow, ui, state, intervalMs = 1000, againMs = 50, now = Date.now }) {
+    Object.assign(this, { flow, ui, state, intervalMs, againMs, now });
+    this.view = null; this.handled = new Set(); this.deferred = new Set(); this.running = null; this.timer = null; this.closed = false;
+  }
+  start() { if (this.timer || this.closed) return this; this.timer = setInterval(() => this.pump(), this.intervalMs); this.timer.unref?.(); return this; }
+  close() { this.closed = true; clearInterval(this.timer); this.timer = null; }
+  update(view) { this.view = normalizeSwarmView(view); this.flow.setView?.(view); this.pump(); }
+  /** /relay vuelve a ofrecer lo que se dejó para después. */
+  retry() { this.deferred.clear(); this.pump(); }
+  idle() {
+    const ui = this.ui;
+    return !this.closed && !ui.closed && !ui.setup && !ui.permission && !ui.selecting && !ui.editingQueue && (!ui.overlay || ['swarm', 'help'].includes(ui.overlay.kind)) && !this.flow.busy;
+  }
+  /** Lo que espera al humano en el proyecto ligado, en orden: criterios de éxito y revisiones
+   *  escaladas (revisor, open-relay F7), planes, preguntas, bloqueos del operador, finales. */
+  async candidates() {
+    const view = this.view, current = this.flow.current;
+    if (!view?.available || view.connection?.mode !== 'cards' || !current?.project) return [];
+    const root = current.hub_root, project = current.project, out = [];
+    try { await adoptLiveSwarms(this.state, view, current); } catch {}
+    for (const swarm of view.swarms) if (criteriaWaiting(swarm.criteria) && swarm.criteria.digest) out.push({ key: `criteria:${swarm.id}:${swarm.criteria.digest}`, kind: 'criteria', project, root, swarm: swarm.id, digest: swarm.criteria.digest });
+    for (const swarm of view.swarms) for (const task of swarm.tasks) if (task.state === 'needs_attention' && task.review_kind) out.push({ key: `escalation:${swarm.id}:${task.id}:${task.review_rounds}`, kind: 'escalation', project, root, swarm: swarm.id, task });
+    for (const swarm of view.swarms) for (const plan of swarm.plans || []) if (plan.proposal_id) out.push({ key: `plan:${swarm.id}:${plan.proposal_id}`, kind: 'plan', project, root, swarm: swarm.id, proposal_id: plan.proposal_id });
+    for (const swarm of view.swarms) for (const item of swarm.pending || []) if (item.kind === 'question' && item.message_id) {
+      const task = item.task ? swarm.tasks.find(entry => entry.id === item.task) || { id: item.task } : null;
+      out.push({ key: `question:${swarm.id}:${item.message_id}`, kind: 'question', project, root, swarm: swarm.id, message_id: item.message_id, task });
+    }
+    for (const swarm of view.swarms) for (const task of swarm.tasks) if (blockedForOperator(task)) out.push({ key: blockedKey(swarm.id, task), kind: 'blocked', project, root, swarm: swarm.id, task });
+    for (const swarm of view.swarms) if (swarmFinished(swarm)) {
+      const tracked = await this.state.swarm(project, swarm.id);
+      if (tracked && !tracked.finished_at) out.push({ key: `finish:${swarm.id}`, kind: 'finish', project, root, swarm: swarm.id, view: swarm, repo: current.repo });
+    }
+    return out;
+  }
+  pump() {
+    if (this.running || !this.idle()) return this.running;
+    let shown = false;
+    this.running = (async () => {
+      const next = (await this.candidates()).find(item => !this.handled.has(item.key) && !this.deferred.has(item.key));
+      if (!next || !this.idle()) return;
+      shown = true;
+      this.flow.busy = true;
+      let result;
+      try {
+        result = await this.flow[DECIDERS[next.kind]](next);
+      } catch (error) { result = 'later'; this.ui.notice(t('/relay card failed: {error}', { error: error.message }), true); }
+      finally { this.flow.busy = false; if (this.ui.setup?.kind === 'status') this.ui.clearSetup(); }
+      if (result === 'decided') this.handled.add(next.key);
+      else { this.deferred.add(next.key); this.ui.notice(t('{what} is waiting for you: /relay shows it again.', { what: t(WAITING[next.kind]) })); }
+    })().finally(() => { this.running = null; if (shown && !this.closed && this.againMs !== null) setTimeout(() => this.pump(), this.againMs).unref?.(); });
+    return this.running;
+  }
+}

package/src/relay/git.mjs

@@ -0,0 +1,23 @@
+import { execFile } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+
+// Lecturas de git para /relay: raíz del repo y cambios de la rama del enjambre. Sólo
+// lectura (rev-parse, merge-base, diff); nunca toca el árbol de trabajo ni las ramas.
+const run = (cwd, args, { maxBuffer = 4 << 20 } = {}) => new Promise((resolve, reject) => {
+  execFile('git', ['-C', cwd, ...args], { maxBuffer, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', LC_ALL: 'C' } }, (error, stdout, stderr) => {
+    if (error) reject(Object.assign(new Error(`git ${args[0]}: ${String(stderr || error.message).trim().slice(0, 400)}`), { code: 'RELAY_GIT' })); else resolve(stdout);
+  });
+});
+const REF = /^[A-Za-z0-9][A-Za-z0-9._\/-]{0,199}$/;
+const ref = value => { if (!REF.test(String(value || '')) || String(value).includes('..')) throw Object.assign(new Error(`Invalid git ref: ${value}`), { code: 'RELAY_GIT' }); return value; };
+
+export const relayGit = {
+  async toplevel(cwd) { return realpath((await run(cwd, ['rev-parse', '--show-toplevel'])).trim()); },
+  async commit(repo, name) { return (await run(repo, ['rev-parse', '--verify', '--quiet', `${ref(name)}^{commit}`])).trim(); },
+  async mergeBase(repo, a, b) { return (await run(repo, ['merge-base', ref(a), ref(b)])).trim(); },
+  async diffStat(repo, base, branch) { return run(repo, ['diff', '--stat=120', `${ref(base)}..${ref(branch)}`], { maxBuffer: 1 << 20 }); },
+  async diff(repo, base, branch, { maxLines = 400 } = {}) {
+    const text = await run(repo, ['diff', `${ref(base)}..${ref(branch)}`], { maxBuffer: 16 << 20 }), lines = text.split('\n');
+    return lines.length > maxLines ? { text: lines.slice(0, maxLines).join('\n'), truncated: lines.length - maxLines } : { text, truncated: 0 };
+  },
+};

package/src/relay/hub-client.mjs

@@ -0,0 +1,163 @@
+import { open, readFile, stat, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { spawn as spawnProcess } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+
+// Cliente de la API local de relay-hub (open-relay v2.10): `POST /v1/rpc {method, params}`
+// en loopback con `Authorization: Bearer <raíz>/hub.token`. Es una herramienta del HUMANO:
+// sólo la usa el comando /relay del host (tarjetas confirmadas por la persona); ninguna
+// operación del modelo llega aquí. El token se lee en cada llamada (es nuevo en cada
+// `relay-hub serve`) y nunca sale de este módulo.
+// open-relay 2.12 añade `project.attach` (diseño de referencia). Aquí no hay lista blanca de
+// métodos: /relay sólo ofrece esa tarjeta si el hub declara la capacidad (`attach` en
+// project.detect) o si su /v1/health publica versión >= 2.12, y la llama antes de swarm.start.
+export const HUB_TOKEN = 'hub.token';
+export const HUB_CONFIG = 'hub.json';
+export const DEFAULT_LISTEN = '127.0.0.1:7379';
+export const HUB_UNIT = 'relay-hub';
+const TOKEN = /^[A-Za-z0-9_-]{16,256}$/;
+const LOOPBACK = /^(?:127\.0\.0\.1|localhost|\[::1\]):(\d{1,5})$/;
+const fail = (code, message, extra = {}) => Object.assign(new Error(message), { code, ...extra });
+const expand = value => value === '~' ? os.homedir() : value.startsWith('~/') ? path.join(os.homedir(), value.slice(2)) : value;
+const shellWord = value => /^[A-Za-z0-9_./:=@%+-]+$/.test(value) ? value : `'${String(value).replace(/'/g, `'\\''`)}'`;
+
+/** Raíz del hub: $RELAY_HUB_ROOT, la guardada con /relay hub RAÍZ o ~/.relay-hub (la de relay-hub). */
+export function hubRoot({ env = process.env, saved } = {}) {
+  if (env.RELAY_HUB_ROOT) return { root: path.resolve(expand(env.RELAY_HUB_ROOT)), source: 'env' };
+  if (saved) return { root: path.resolve(expand(saved)), source: 'saved' };
+  return { root: path.join(os.homedir(), '.relay-hub'), source: 'default' };
+}
+
+/** Lee el token del hub: archivo regular del usuario, 0600, sin seguir symlinks. */
+export async function readHubToken(file) {
+  let handle;
+  try {
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const info = await handle.stat(), uid = process.getuid?.();
+    if (!info.isFile() || info.size > 1024 || (uid !== undefined && info.uid !== uid) || (info.mode & 0o077)) throw fail('RELAY_HUB_TOKEN_UNSAFE', `${file} is not a private (0600) file owned by the user.`);
+    const token = (await handle.readFile('utf8')).trim();
+    if (!TOKEN.test(token)) throw fail('RELAY_HUB_TOKEN_INVALID', `${file} does not contain a hub token.`);
+    return token;
+  } catch (error) {
+    if (error.code === 'ENOENT') throw fail('RELAY_HUB_DOWN', `relay-hub is not running (no ${file}).`);
+    if (error.code === 'ELOOP') throw fail('RELAY_HUB_TOKEN_UNSAFE', `${file} is a symlink.`);
+    throw error;
+  } finally { await handle?.close(); }
+}
+
+async function executable(file) { try { await access(file, constants.X_OK); return (await stat(file)).isFile(); } catch { return false; } }
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+export class HubClient {
+  constructor({ root, bin, env = process.env, fetch = globalThis.fetch, spawn = spawnProcess, wait = sleep, startTimeoutMs = 20000 } = {}) {
+    Object.assign(this, { root: path.resolve(root || hubRoot({ env }).root), bin, env, fetch, spawn, wait, startTimeoutMs });
+  }
+  get tokenFile() { return path.join(this.root, HUB_TOKEN); }
+  get configFile() { return path.join(this.root, HUB_CONFIG); }
+  /** `hub.json` de `relay-hub init`. Sin él, el error trae el comando para crearlo. */
+  async config() {
+    let text;
+    try { text = await readFile(this.configFile, 'utf8'); }
+    catch (error) {
+      if (error.code === 'ENOENT') throw fail('RELAY_HUB_NOT_INITIALIZED', `No relay-hub at ${this.root} (missing ${HUB_CONFIG}). Create it once: relay-hub --root ${shellWord(this.root)} init --open-relay <checkout> --comal <bin/comal.mjs> --node-dir <node/bin> --credential-file <0600 key file>. Or point Comal to an existing hub: /relay hub <root> (or RELAY_HUB_ROOT).`);
+      throw error;
+    }
+    let config; try { config = JSON.parse(text); } catch { throw fail('RELAY_HUB_CONFIG', `${this.configFile} is not JSON.`); }
+    if (!config || typeof config !== 'object') throw fail('RELAY_HUB_CONFIG', `${this.configFile} is not an object.`);
+    return config;
+  }
+  /** Dirección de la API: sólo loopback (como la exige relay-hub). */
+  async listen() {
+    const config = await this.config().catch(() => ({}));
+    const listen = typeof config.listen === 'string' ? config.listen : DEFAULT_LISTEN;
+    const match = LOOPBACK.exec(listen);
+    if (!match || Number(match[1]) < 1 || Number(match[1]) > 65535) throw fail('RELAY_HUB_CONFIG', `The hub API must listen on loopback, not ${listen}.`);
+    return listen;
+  }
+  async health({ signal } = {}) {
+    try {
+      const response = await this.fetch(`http://${await this.listen()}/v1/health`, { signal: AbortSignal.any([signal, AbortSignal.timeout(3000)].filter(Boolean)) });
+      if (!response.ok) return null;
+      const body = await response.json();
+      return body?.ok ? body : null;
+    } catch (error) { if (signal?.aborted) throw error; return null; }
+  }
+  async ready({ signal } = {}) {
+    const health = await this.health({ signal }); if (!health) return null;
+    try { await readHubToken(this.tokenFile); return health; } catch { return null; }
+  }
+  /** Una llamada a la API; con 401 relee el token una vez (el hub pudo reiniciarse). */
+  async call(method, params = {}, { signal, timeoutMs = 150000 } = {}) {
+    for (let attempt = 0; ; attempt++) {
+      const token = await readHubToken(this.tokenFile), url = `http://${await this.listen()}/v1/rpc`;
+      let response;
+      try {
+        response = await this.fetch(url, {
+          method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+          body: JSON.stringify({ method, params }), signal: AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)].filter(Boolean)),
+        });
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        throw fail('RELAY_HUB_DOWN', `relay-hub did not answer ${method} (${error.cause?.code || error.name || error.message}).`);
+      }
+      let body; try { body = await response.json(); } catch { throw fail('RELAY_HUB_PROTOCOL', `relay-hub answered ${method} with HTTP ${response.status} and no JSON.`); }
+      if (body?.error) {
+        if (response.status === 401 && !attempt) continue;
+        throw fail(String(body.error.code || 'RELAY_HUB_ERROR'), String(body.error.message || 'relay-hub error').slice(0, 2000), { hub: true, status: response.status, method });
+      }
+      if (!response.ok) throw fail('RELAY_HUB_PROTOCOL', `relay-hub answered ${method} with HTTP ${response.status}.`);
+      return body.result;
+    }
+  }
+  /** El binario relay-hub: RELAY_HUB_BIN, el guardado, PATH o el checkout de open-relay de hub.json. */
+  async binary(config) {
+    const candidates = [this.env.RELAY_HUB_BIN, this.bin];
+    for (const dir of String(this.env.PATH || '').split(path.delimiter).filter(Boolean)) candidates.push(path.join(dir, 'relay-hub'));
+    if (config?.bin_dir) candidates.push(path.join(expand(config.bin_dir), 'relay-hub'));
+    if (config?.open_relay) candidates.push(path.join(expand(config.open_relay), 'target', 'release', 'relay-hub'));
+    for (const candidate of candidates.filter(Boolean)) if (path.isAbsolute(candidate) && await executable(candidate)) return candidate;
+    throw fail('RELAY_HUB_BINARY', `relay-hub not found (RELAY_HUB_BIN, PATH or ${config?.open_relay ? path.join(config.open_relay, 'target/release') : 'the open-relay checkout of hub.json'}).`);
+  }
+  /**
+   * Asegura la API: si no responde, arranca `relay-hub --root <raíz> serve` como unidad
+   * transitoria de systemd de usuario (`relay-hub`, loopback, sin reinicio) o, sin systemd,
+   * como proceso desacoplado. Devuelve {started, unit?, listen}.
+   */
+  async ensure({ signal } = {}) {
+    const listen = await this.listen();
+    if (await this.ready({ signal })) return { started: false, listen };
+    const config = await this.config(), bin = await this.binary(config);
+    const args = ['--root', this.root, 'serve'];
+    const launched = await this.#launch(bin, args, signal);
+    for (const deadline = Date.now() + this.startTimeoutMs; Date.now() < deadline;) {
+      signal?.throwIfAborted();
+      if (await this.ready({ signal })) return { started: true, listen, bin, ...launched };
+      await this.wait(200);
+    }
+    throw fail('RELAY_HUB_START', `relay-hub did not start on ${listen} within ${Math.round(this.startTimeoutMs / 1000)} s${launched.unit ? ` (journalctl --user -u ${launched.unit})` : ''}.`);
+  }
+  async #run(command, args) {
+    return new Promise(resolve => {
+      let child; try { child = this.spawn(command, args, { stdio: ['ignore', 'ignore', 'pipe'] }); } catch (error) { resolve({ code: -1, error }); return; }
+      let stderr = ''; child.stderr?.on('data', chunk => { stderr = (stderr + chunk).slice(-2000); });
+      child.once('error', error => resolve({ code: -1, error, stderr }));
+      child.once('exit', code => resolve({ code, stderr }));
+    });
+  }
+  async #launch(bin, args) {
+    const unit = await this.#run('systemd-run', ['--user', `--unit=${HUB_UNIT}`, '--collect', '--quiet', '-p', 'Restart=no', '--', bin, ...args]);
+    if (unit.code === 0) return { unit: HUB_UNIT };
+    if (unit.error?.code !== 'ENOENT') {
+      // Una unidad vieja con el mismo nombre (fallida): se limpia y se reintenta una vez.
+      await this.#run('systemctl', ['--user', 'reset-failed', `${HUB_UNIT}.service`]);
+      const retry = await this.#run('systemd-run', ['--user', `--unit=${HUB_UNIT}`, '--collect', '--quiet', '-p', 'Restart=no', '--', bin, ...args]);
+      if (retry.code === 0) return { unit: HUB_UNIT };
+      if (/already (exists|loaded)/i.test(retry.stderr || '')) return { unit: HUB_UNIT, existing: true };
+      throw fail('RELAY_HUB_START', `systemd-run could not start relay-hub: ${(retry.stderr || unit.stderr || '').trim().slice(0, 400)}`);
+    }
+    // Sin systemd (p. ej. macOS): proceso desacoplado, que sigue vivo al salir de Comal.
+    const child = this.spawn(bin, args, { detached: true, stdio: 'ignore' }); child.unref?.();
+    return { pid: child.pid };
+  }
+}

package/src/relay/state.mjs

@@ -0,0 +1,55 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readPrivateJson, writePrivateJson } from '../permission-rules.mjs';
+
+// Estado de /relay por usuario, fuera de cualquier workspace (como plugin-trust.json): qué
+// proyecto del hub está ligado a cada repo, la raíz del hub elegida y los swarms que el
+// humano arrancó desde Comal o que Comal adoptó vivos al seguir el proyecto (`adopted_at`),
+// para la tarjeta final, una sola vez. Nada de tokens.
+const VERSION = 1, MAX_LINKS = 256, MAX_SWARMS = 512;
+const NAME = /^[a-z][a-z0-9-]{0,39}$/, SWARM = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+
+export function relayStateFile(env = process.env) {
+  return path.resolve(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'comal', 'relay.json');
+}
+const empty = () => ({ version: VERSION, hub_root: null, links: {}, swarms: {} });
+const text = (value, limit) => typeof value === 'string' ? value.slice(0, limit) : null;
+
+function clean(data) {
+  const out = empty();
+  if (!data || typeof data !== 'object' || data.version !== VERSION) return out;
+  if (typeof data.hub_root === 'string' && path.isAbsolute(data.hub_root)) out.hub_root = data.hub_root;
+  for (const [repo, link] of Object.entries(data.links || {}).slice(-MAX_LINKS)) {
+    if (!path.isAbsolute(repo) || !link || !NAME.test(link.project || '')) continue;
+    out.links[repo] = { project: link.project, hub_root: text(link.hub_root, 1024), branch: text(link.branch, 200), base_commit: text(link.base_commit, 64), linked_at: text(link.linked_at, 40) };
+  }
+  for (const [key, swarm] of Object.entries(data.swarms || {}).slice(-MAX_SWARMS)) {
+    const [project, id] = key.split('/');
+    if (!NAME.test(project || '') || !SWARM.test(id || '') || !swarm) continue;
+    out.swarms[key] = { objective: text(swarm.objective, 4000), started_at: text(swarm.started_at, 40), base_commit: text(swarm.base_commit, 64), branch: text(swarm.branch, 200), finished_at: text(swarm.finished_at, 40), ...(swarm.adopted_at ? { adopted_at: text(swarm.adopted_at, 40) } : {}) };
+  }
+  return out;
+}
+
+export class RelayState {
+  constructor({ file = relayStateFile(), workspace } = {}) { this.file = path.resolve(file); this.workspace = workspace; this.data = empty(); this.warning = null; this.loaded = false; }
+  async load() {
+    this.warning = null;
+    try { this.data = clean(await readPrivateJson(this.file, { workspace: this.workspace })); }
+    catch (error) { this.data = empty(); this.warning = error.message; }
+    this.loaded = true; return this;
+  }
+  async #ready() { if (!this.loaded) await this.load(); }
+  async save() {
+    if (this.warning) throw Object.assign(new Error(`${this.warning} Fix or delete ${this.file}.`), { code: 'RELAY_STATE_UNSAFE' });
+    await writePrivateJson(this.file, this.data, { workspace: this.workspace });
+  }
+  async hubRoot() { await this.#ready(); return this.data.hub_root; }
+  async setHubRoot(root) { await this.#ready(); this.data.hub_root = root ? path.resolve(root) : null; await this.save(); }
+  async link(repo) { await this.#ready(); return this.data.links[repo] ? { ...this.data.links[repo] } : null; }
+  async setLink(repo, link) { await this.#ready(); delete this.data.links[repo]; this.data.links[repo] = { ...link, linked_at: new Date().toISOString() }; this.data = clean(this.data); await this.save(); }
+  async unlink(repo) { await this.#ready(); if (!this.data.links[repo]) return false; delete this.data.links[repo]; await this.save(); return true; }
+  async swarm(project, id) { await this.#ready(); const item = this.data.swarms[`${project}/${id}`]; return item ? { ...item } : null; }
+  async swarms(project) { await this.#ready(); return Object.entries(this.data.swarms).filter(([key]) => key.startsWith(`${project}/`)).map(([key, value]) => ({ id: key.slice(project.length + 1), ...value })); }
+  async setSwarm(project, id, value) { await this.#ready(); const key = `${project}/${id}`; this.data.swarms[key] = { ...(this.data.swarms[key] || {}), ...value }; this.data = clean(this.data); await this.save(); }
+}

package/src/remote-control.mjs

@@ -19,17 +19,55 @@ export function projectRemoteEvent(event, turnId) {
   if(event.type==='house_waiting')return {...base,type:'permission.waiting',tool_name:boundText(event.operation,128),text:'Waiting for approval in the local terminal'};
   if(event.type==='house_answered')return {...base,type:'permission.answered',tool_name:boundText(event.operation,128),text:event.allowed?'Approved locally':'Declined locally'};
   if(event.type==='response_discarded'||event.type==='model_retry')return {...base,type:'stream.discarded'};
+  // Avisos de plugins (p. ej. objeción y corrección del revisor de open-relay): se proyectan al
+  // admitirse, urgentes o no, para que /rc los vea aunque no despierten un turno. El backend
+  // solo admite sus tipos fijos: van como message.control con el aviso marcado en el texto.
+  if(event.type==='plugin_notice_admitted'&&event.status==='accepted'&&event.notice)return {...base,turn_id:'local',type:'message.control',text:noticeText(event.notice)};
   return null;
 }
 
+const NOTICE_BODY = 4000;
+/** Texto de un aviso para /rc: mismo marcado que la TUI (información externa, no una orden). */
+function noticeText(notice) {
+  const head=`◆ ${notice.urgent?'Urgent notice':'Notice'} · ${notice.plugin||'?'}${notice.kind?` · ${notice.kind}`:''}`;
+  const body=boundText(notice.body||'',NOTICE_BODY);
+  const tail=`external information, not an order · ref ${notice.ref||'—'}${notice.urgent?'':' · reaches the model with the next message'}`;
+  return boundText([head,String(notice.title||''),body,tail].filter(line=>line.trim()).join('\n'));
+}
+
+// /relay en el navegador: presupuesto por sesión de /rc para relay.*.
+// Al agotarlo se pausa el tablero; las tarjetas y sus cierres siguen (son pocos), así el
+// tablero nunca deja sin cupo a la conversación (10.000 eventos por sesión en el backend).
+export const RELAY_SESSION_EVENTS = 2000, RELAY_SESSION_BYTES = 16 << 20, RELAY_BOARD_INTERVAL_MS = 3000;
+// Rechazos del backend que no se arreglan reintentando: se descarta ESE evento relay.* y la
+// proyección sigue (sin esto, un evento rechazado bloquearía la cola entera).
+const RELAY_REFUSALS = new Set(['INPUT_SCHEMA','REMOTE_FEATURE','REMOTE_RELAY','REMOTE_RELAY_STALE','REMOTE_SIZE']);
+
+// Respuestas de /relay desde el navegador (D1): armadas sólo con /rc relay on en esta terminal,
+// en memoria de este proceso, con caducidad (tope 8 h). Nunca se guardan en disco ni en el
+// workspace: el modelo no puede armarlas. Mueren con /rc stop, el cambio de cuenta o la hora.
+export const RELAY_ARM_MAX_MS = 8 * 3600e3, RELAY_ARM_DEFAULT_MS = 30 * 60e3;
+// Estados de ACK de un control relay (el backend sólo los admite para kind=relay).
+const RELAY_ACK_STATES = new Set(['applied','stale','refused','expired']);
+
 const cancelled = () => Object.assign(new Error('Remote Control connection cancelled.'), {name:'AbortError',code:'REMOTE_CANCELLED'});
 const lifetimeSignal = (run,timeout=10000) => run?.controller ? AbortSignal.any([run.controller.signal,AbortSignal.timeout(timeout)]) : AbortSignal.timeout(timeout);
 
 export class RemoteHost {
-  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
-    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,relay=null,onRelay=null,now=Date.now,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
+    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,relay,onRelay,now,socketFactory});this.answersUntil=0;this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  }
+  status(){const run=this.lifecycle;return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only',relay:run?.relay?(run.answers?'answers':'read_only'):'off',...(run?.answers?{relay_answers:{armed:this.armed(),until:this.armed()?this.answersUntil:null}}:{})}:{enabled:false};}
+  /** ¿Puede esta sesión de /rc responder tarjetas de /relay? (backend con relay_answers_v1). */
+  answersAvailable(){return Boolean(this.current(this.lifecycle)&&this.lifecycle.answers);}
+  armed(){return this.answersAvailable()&&this.answersUntil>this.now();}
+  /** /rc relay on [duración]: arma las respuestas del navegador hasta now+ms (tope 8 h). */
+  arm(ms=RELAY_ARM_DEFAULT_MS){
+    if(!this.answersAvailable())throw Error(this.lifecycle?.relay?'This Comal backend does not accept /relay answers from the browser yet.':'Open /rc in a session linked to /relay first.');
+    const span=Math.min(Math.max(60e3,Math.floor(Number(ms)||RELAY_ARM_DEFAULT_MS)),RELAY_ARM_MAX_MS);
+    this.answersUntil=this.now()+span;this.pulse().catch(()=>{});return this.answersUntil;
   }
-  status(){return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only'}:{enabled:false};}
+  disarm(){this.answersUntil=0;if(this.current(this.lifecycle))this.pulse().catch(()=>{});}
   current(run,{starting=false}={}) {return this.lifecycle===run && (starting || !this.stopped) && !run?.controller?.signal.aborted;}
   assertCurrent(run,options){if(!this.current(run,options))throw cancelled();}
   async revoke(run) {
@@ -49,8 +87,21 @@ export class RemoteHost {
         if(!account)throw Error('Sign in with comal cloud login before enabling Remote Control.');
         run.account={origin:account.origin,user_id:account.user_id};run.enablingToken=account.token;
         const workspace=this.getWorkspace?await this.getWorkspace(session):null;this.assertCurrent(run,{starting:true});
-        const opened=await this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[])]},{expectedAccount:run.account,signal:run.controller.signal});
+        const features=['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[]),...(this.relay?['relay_v1']:[]),...(this.relay&&this.onRelay?['relay_answers_v1']:[])];
+        const open=list=>this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:list},{expectedAccount:run.account,signal:run.controller.signal});
+        // Un backend anterior rechaza la capacidad desconocida en el esquema de Milpa (no se crea
+        // sesión): se reintenta sin relay_answers_v1 (backend de la fase «ver») y después sin
+        // relay_v1 (backend anterior a /relay). /rc se abre igual con lo que el backend admite.
+        const attempts=[features,features.filter(item=>item!=='relay_answers_v1'),features.filter(item=>!item.startsWith('relay_'))].filter((list,index,all)=>index===0||list.length<all[index-1].length);
+        let opened,used=attempts[0];
+        for(const [index,list] of attempts.entries()){
+          try{used=list;opened=await open(list);break;}
+          catch(error){if(error.code!=='INPUT_SCHEMA'||index===attempts.length-1)throw error;this.assertCurrent(run,{starting:true});}
+        }
+        run.relayRefused=Boolean(this.relay)&&!used.includes('relay_v1');
         run.session=opened.session;
+        const granted=feature=>used.includes(feature)&&(!Array.isArray(opened.session?.features)||opened.session.features.includes(feature));
+        run.relay=Boolean(this.relay)&&granted('relay_v1');run.answers=run.relay&&Boolean(this.onRelay)&&granted('relay_answers_v1');this.answersUntil=0;
         // Abort can race a successful response. Revoke a late-created grant even
         // when the local stop completed before its identifier became available.
         if(!this.current(run,{starting:true})){await this.revoke(run);throw cancelled();}
@@ -58,12 +109,13 @@ export class RemoteHost {
         await this.authorize(run);this.assertCurrent(run);await this.pulse(run);this.assertCurrent(run);
         this.transport='https-polling';this.connectSocket(run);
         if(workspace)this.publishWorkspace(workspace,run);
+        if(run.relay){run.relaySink={extended:run.answers,relayBoard:(board,options)=>this.relayBoard(board,options,run),relayEvent:(type,relay)=>this.relayEvent(type,relay,run)};this.relay.attach(run.relaySink);}
         this.timer=setInterval(()=>this.tick(run),1000);this.timer.unref();
         for(const message of (session.historyMessages || []).slice(-20)){
           const event=message.role==='user'&&(typeof message.content==='string'||Array.isArray(message.content)&&message.content.some(block=>block.type==='text'))?{type:'user',text:typeof message.content==='string'?message.content:message.content.filter(block=>block.type==='text').map(block=>block.text).join('\n')}:message.role==='assistant'?{type:'assistant',message}:null;
           if(event)this.observe(event);
         }
-        this.onNotice('Remote Control: '+this.url+' · transcript stored on your Comal backend; permissions stay in this terminal.');
+        this.onNotice('Remote Control: '+this.url+' · transcript stored on your Comal backend; permissions stay in this terminal.'+(run.answers?' /relay is visible there; to answer its cards from the browser run /rc relay on here (off by default).':run.relay?' /relay is visible there read-only; answer its cards here.':run.relayRefused?' This backend does not show /relay yet.':''));
         return this.status();
       } catch(error) {
         if(this.lifecycle===run)await this.stop();else await this.revoke(run);
@@ -113,6 +165,41 @@ export class RemoteHost {
     this.pending.push({event_id:randomUUID(),event:{type:'workspace.snapshot',text:'',turn_id:this.turnId||'local',workspace}});
     run.workspaceDigest=key;this.flush(run).catch(()=>{});
   }
+  /** Tablero de /swarm: coalescido (≥ 3 s), sin repetir huella y «el último gana» en el búfer. */
+  relayBoard(board,{now=false}={},run=this.lifecycle) {
+    if(!this.current(run)||!run.relay)return;
+    const {source,...content}=board,key=digest(content);
+    run.boardNext=key===run.boardDigest?null:board;run.boardNextKey=key;
+    if(!run.boardNext)return;
+    const wait=now?0:Math.max(0,(run.boardAt||0)+RELAY_BOARD_INTERVAL_MS-Date.now());
+    if(!wait){clearTimeout(run.boardTimer);run.boardTimer=null;this.pushRelayBoard(run);return;}
+    if(!run.boardTimer){run.boardTimer=setTimeout(()=>{run.boardTimer=null;this.pushRelayBoard(run);},wait);run.boardTimer.unref?.();}
+  }
+  pushRelayBoard(run=this.lifecycle) {
+    if(!this.current(run)||!run.boardNext||run.boardPaused)return;
+    let board=run.boardNext;const key=run.boardNextKey;run.boardNext=null;
+    if((run.relayEvents||0)>=RELAY_SESSION_EVENTS||(run.relayBytes||0)>=RELAY_SESSION_BYTES){
+      run.boardPaused=true;board={...board,swarms:[],paused:true,omitted:{swarms:board.swarms_total||0,tasks:0}};
+      this.onNotice('Remote /relay board paused: this /rc session reached its relay budget. Cards still reach the browser; /swarm here keeps the live board.');
+    }
+    // El backend no admite un tablero que retroceda en el tiempo de su foto.
+    const seen=Math.max(Number(board.source?.view_generated_at)||1,run.boardSeen||1);board={...board,source:{...board.source,view_generated_at:seen}};run.boardSeen=seen;
+    const entry={event_id:randomUUID(),event:{type:'relay.board',text:'',turn_id:'local',relay:board}};
+    if(Buffer.byteLength(JSON.stringify(board))>36000)return;
+    const index=this.pending.findIndex((item,position)=>item.event.type==='relay.board'&&(position>0||!this.sending));
+    if(index>=0)this.pending[index]=entry;
+    else{if(this.pending.length>=512)return;this.pending.push(entry);}
+    run.boardDigest=key;run.boardAt=Date.now();this.relayAccount(run,entry.event);this.flush(run).catch(()=>{});
+  }
+  /** relay.card, relay.card.page y relay.resolved: siempre salen (dentro del búfer de 512). */
+  relayEvent(type,relay,run=this.lifecycle) {
+    if(!this.current(run)||!run.relay)return false;
+    if(Buffer.byteLength(JSON.stringify(relay))>36000)return false;
+    if(this.pending.length>=512){this.onNotice('Remote /relay card skipped: outbound buffer full. The card stays in this terminal.');return false;}
+    const entry={event_id:randomUUID(),event:{type,text:'',turn_id:'local',relay}};
+    this.pending.push(entry);this.relayAccount(run,entry.event);this.flush(run).catch(()=>{});return true;
+  }
+  relayAccount(run,event){run.relayEvents=(run.relayEvents||0)+1;run.relayBytes=(run.relayBytes||0)+Buffer.byteLength(JSON.stringify(event));}
   invalidateWorkspace() {
     const run=this.lifecycle;if(!this.current(run)||!this.getWorkspace)return;
     run.workspaceDirty=true;
@@ -157,10 +244,15 @@ export class RemoteHost {
   async flush(run=this.lifecycle){
     if(!this.current(run))return;
     if(this.sending)return this.sending;
-    const work=(async()=>{while(this.current(run)&&this.pending.length){await this.call('remote.events.publish',this.pending[0],run);this.assertCurrent(run);this.pending.shift();}})();
+    const work=(async()=>{while(this.current(run)&&this.pending.length){
+      const item=this.pending[0];
+      try{await this.call('remote.events.publish',item,run);}
+      catch(error){if(!this.current(run)||!String(item.event?.type).startsWith('relay.')||!RELAY_REFUSALS.has(error.code))throw error;this.onNotice('Remote /relay event refused by the backend ('+error.code+'); /relay and /swarm in this terminal are unaffected.');}
+      this.assertCurrent(run);if(this.pending[0]===item)this.pending.shift();else{const index=this.pending.indexOf(item);if(index>=0)this.pending.splice(index,1);}
+    }})();
     this.sending=work;try{return await work;}finally{if(this.sending===work)this.sending=null;}
   }
-  pulse(run=this.lifecycle){const work=(this.pulsing || Promise.resolve()).catch(()=>{}).then(()=>{if(this.current(run))return this.call('remote.host.pulse',{status:this.turnId?'busy':'idle',turn_id:this.turnId},run);});this.pulsing=work;return work;}
+  pulse(run=this.lifecycle){const work=(this.pulsing || Promise.resolve()).catch(()=>{}).then(()=>{if(!this.current(run))return;const armed=run.answers&&this.answersUntil>this.now();return this.call('remote.host.pulse',{status:this.turnId?'busy':'idle',turn_id:this.turnId,...(run.answers?{relay_answers:{armed,until:armed?Math.floor(this.answersUntil/1000):0}}:{})},run);});this.pulsing=work;return work;}
   async beginTurn(){this.turnId=randomUUID();if(!this.stopped)this.pulse().catch(error=>{if(error.code!=='REMOTE_CANCELLED')this.onNotice('Remote state unavailable: '+error.message);});}
   async endTurn(){
     this.invalidateWorkspace();
@@ -179,13 +271,14 @@ export class RemoteHost {
       await this.pulse(run);this.assertCurrent(run);await this.flush(run);this.assertCurrent(run);
       const page=await this.call('remote.inputs.claim',{},run);this.assertCurrent(run);
       for(const input of page.inputs){
-        this.assertCurrent(run);let state='accepted_locally',queue_item_id='';
+        this.assertCurrent(run);let state='accepted_locally',queue_item_id='',outcome=null;
         // Only admission errors are rejection. A lost ACK must redeliver the same input.
-        try {
+        if(input.kind==='relay'){({state,outcome}=await this.relayAnswer(input,run));}
+        else try {
           if(input.kind==='stop'){if(input.turn_id!==this.turnId||!await this.onStop(input.turn_id))throw Error('Stale turn.');queue_item_id='stop:'+input.turn_id;}
           else {const accepted=await this.onInput(input,{session:this.session.id,request:input.request_id});queue_item_id=accepted.id;}
         }catch{state='rejected';}
-        this.assertCurrent(run);await this.call('remote.inputs.ack',{request_id:input.request_id,state,queue_item_id},run);
+        this.assertCurrent(run);await this.call('remote.inputs.ack',{request_id:input.request_id,state,queue_item_id,...(outcome?{outcome}:{})},run);
       }
       if(!this.socket&&Date.now()>this.nextSocketAt)this.connectSocket(run);
     })().catch(error=>{
@@ -195,10 +288,20 @@ export class RemoteHost {
     });
     this.processing=work;try{return await work;}finally{if(this.processing===work)this.processing=null;}
   }
+  /** Control tipado del navegador sobre una tarjeta de /relay (kind=relay). Nunca entra en la cola
+   *  del modelo: lo revalida y aplica el broker local con las funciones de la TUI. */
+  async relayAnswer(input,run=this.lifecycle){
+    if(!run?.answers||!this.onRelay)return {state:'refused',outcome:'host_legacy'};
+    try{
+      const result=await this.onRelay(input,{session:this.session.id,epoch:this.session.host_epoch,armed:()=>this.armed(),validate:()=>this.validate({remote:{session:this.session.id,request:input.request_id}})});
+      const state=RELAY_ACK_STATES.has(result?.state)?result.state:'refused';
+      return {state,outcome:/^[a-z_]{1,64}$/.test(String(result?.outcome||''))?result.outcome:'host_error'};
+    }catch(error){if(!this.current(run))throw error;return {state:'refused',outcome:'host_error'};}
+  }
   async stop(){
     const run=this.lifecycle || {session:this.session,account:this.account,enablingToken:this.enablingToken};
-    this.lifecycle=null;this.starting=null;run.controller?.abort();clearTimeout(run.workspaceTimer);
-    this.stopped=true;clearInterval(this.timer);clearTimeout(this.deltaTimer);clearTimeout(this.socketTimeout);this.socket?.close();this.socket=null;this.delta='';this.transport='disconnected';
+    this.lifecycle=null;this.starting=null;run.controller?.abort();clearTimeout(run.workspaceTimer);clearTimeout(run.boardTimer);if(run.relaySink)this.relay?.detach(run.relaySink);
+    this.stopped=true;this.answersUntil=0;clearInterval(this.timer);clearTimeout(this.deltaTimer);clearTimeout(this.socketTimeout);this.socket?.close();this.socket=null;this.delta='';this.transport='disconnected';
     this.access=null;this.enablingToken=null;this.pending=[];this.turnId=null;this.processing=null;this.sending=null;this.pulsing=null;this.connecting=null;
     await this.revoke(run);return this.status();
   }