@milpa/comal 0.2.2 → 0.2.4

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