@milpa/comal 0.2.1 → 0.2.3

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

@@ -1,37 +1,138 @@
-import { reconnectable } from './client.mjs';
-import { deliveryNotice, planNotice, taskAlert, jobAlert } from './notices.mjs';
+import { needsHuman } from './client.mjs';
+import { deliveryNotice, planNotice, taskAlert, jobAlert, reviewAlert, correctionNotice } from './notices.mjs';
+import { clean, excerpt } from './bound.mjs';
+import { decisionBlock } from './decision.mjs';
 
-// Vigilancia del enjambre, como `relay msg watch --operator`: una conexión
-// dedicada por swarm para `msg.wait` (espera larga), otra para `swarm.status`
-// con `if_changed`, descubrimiento de swarms cada pocos segundos y sondeo de jobs.
-// No hay push por socket. Deduplica por ref y guarda el cursor del buzón por swarm.
+// Vigilancia del enjambre sin sondeo (fase 3, open-relay ≥ 2.8): una conexión dedicada
+// hace `events.wait {after, timeout_ms}` en bucle sobre el log de relayd. Al conectar
+// por primera vez se toma el `head_seq` y se revisa lo que ya estaba pendiente (buzón
+// del operador, tareas, planes y jobs); después sólo se mira lo que tocan los eventos:
+// `message_sent` al operador → buzón de ese swarm; `task:*` → foto del swarm (alertas y
+// estados); `plan:*` → planes pendientes; `job:*` → jobs. Si la espera vence
+// (`timed_out`), se repite con el mismo `after`. Ante un corte (relayd reiniciado,
+// UNAVAILABLE) reconecta con espera creciente y sigue desde su cursor: lo que pasó
+// mientras tanto llega en la siguiente espera. Deduplica por ref.
+// Fase 4: con lo que ya lee, guarda además una foto ACOTADA y limpia para el panel /swarm
+// (tareas, roles, preguntas y planes pendientes) y avisa con onChange; no hace llamadas
+// extra salvo releer el buzón cuando relayd registra un ack o vencimiento de una entrega del
+// operador, y la foto del swarm cuando cambian sus roles o equipos.
 const sleep = (ms, signal) => new Promise(resolve => { const timer = setTimeout(done, ms); function done() { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); } signal?.addEventListener('abort', done, { once: true }); });
-const SEEN_LIMIT = 4000, PAGE = 200;
+const SEEN_LIMIT = 4000, PAGE = 200, TASKS_SHOWN = 40;
+// Topes de la foto del panel (texto de agentes: limpio y acotado ya aquí).
+const VIEW = Object.freeze({ swarms: 16, tasks: 80, roles: 40, pending: 30, plans: 20, title: 160, objective: 300, excerpt: 240, id: 120 });
+const short = (value, limit = VIEW.id) => { const text = clean(value).replace(/\s+/g, ' ').trim(); return text.length > limit ? text.slice(0, limit) + '…' : text; };
+const stamp = value => { const number = Number(value); return Number.isFinite(number) && number > 0 ? number : null; };
+const splitAggregate = value => { const text = String(value || ''), at = text.indexOf(':'); return at < 0 ? [text, ''] : [text.slice(0, at), text.slice(at + 1)]; };
 
 export class RelayWatcher {
-  constructor({ client, notify, swarms = null, waitMs = 30000, discoverMs = 3000, jobsMs = 5000, questionGraceMs = 1200, maxBackoffMs = 5000, onError = () => {} }) {
-    Object.assign(this, { client, notify, filter: swarms && swarms.length ? new Set(swarms) : null, waitMs, discoverMs, jobsMs, questionGraceMs, maxBackoffMs, onError });
-    this.controller = new AbortController(); this.workers = new Map(); this.cursors = new Map(); this.digests = new Map();
-    this.seen = new Set(); this.retry = []; this.connections = new Set(); this.sent = 0; this.lastError = null; this.started = false;
+  constructor({ client, notify, swarms = null, waitMs = 30000, questionGraceMs = 1200, maxBackoffMs = 5000, humanBackoffMs = 30000, batch = 200, onError = () => {}, onChange = () => {}, now = Date.now }) {
+    Object.assign(this, { client, notify, filter: swarms && swarms.length ? new Set(swarms) : null, waitMs, questionGraceMs, maxBackoffMs, humanBackoffMs, batch, onError, onChange, now });
+    // Foto del panel: por swarm, resumen, tareas (con desde cuándo se ve su estado), roles,
+    // entregas pendientes del operador y planes pendientes. Todo limpio y acotado.
+    this.info = new Map(); this.board = new Map(); this.since = new Map(); this.pending = new Map(); this.proposals = new Map(); this.criteria = new Map();
+    this.questionTask = new Map(); this.messageSwarm = new Map(); this.roleSwarm = new Map(); this.updatedAt = null;
+    this.controller = new AbortController(); this.known = new Set(); this.taskStates = new Map(); this.taskSwarm = new Map();
+    this.seen = new Set(); this.retry = []; this.connection = null; this.sent = 0; this.lastError = null; this.started = false;
+    this.cursor = null; this.events = 0; this.waits = 0; this.opened = 0; this.lastEvent = null; this.state = 'idle'; this.loop = null;
   }
   get signal() { return this.controller.signal; }
   status() {
-    return { watching: [...this.workers.keys()], filter: this.filter ? [...this.filter] : null, cursors: Object.fromEntries(this.cursors), notices_sent: this.sent, pending_retry: this.retry.length, reconnects: Math.max(0, this.client.connects - 1), last_error: this.lastError };
-  }
-  start() {
-    if (this.started) return; this.started = true;
-    this.#loop('discover', () => this.#discover(), this.discoverMs);
-    this.#loop('jobs', () => this.#jobs(), this.jobsMs);
-  }
-  async stop() { this.controller.abort(new Error('Watch stopped.')); for (const connection of this.connections) connection.close(); this.connections.clear(); await Promise.allSettled([...this.workers.values()].flat()); }
-  #error(where, error) { if (this.signal.aborted) return; this.lastError = { where, code: error.code || 'ERROR', message: String(error.message).slice(0, 300), at: new Date().toISOString() }; this.onError(this.lastError); }
-  #loop(name, step, every) {
-    (async () => {
-      while (!this.signal.aborted) {
-        try { await step(); } catch (error) { this.#error(name, error); }
-        await sleep(every, this.signal);
+    const tasks = {};
+    for (const [swarm, states] of this.taskStates) tasks[swarm] = Object.fromEntries([...states].slice(-TASKS_SHOWN));
+    return { state: this.state, watching: [...this.known], filter: this.filter ? [...this.filter] : null, cursor: this.cursor, events_seen: this.events, waits: this.waits, last_event: this.lastEvent, tasks, notices_sent: this.sent, pending_retry: this.retry.length, reconnects: Math.max(0, this.opened - 1), last_error: this.lastError };
+  }
+  start() { if (this.started) return; this.started = true; this.loop = this.#run(); }
+  #state(state) { if (this.state === state) return; this.state = state; this.#changed(); }
+  #changed() { this.updatedAt = this.now(); try { this.onChange(); } catch {} }
+  /** Foto para el panel /swarm: datos ya limpios y acotados, sin tokens ni rutas del token. */
+  view() {
+    const swarms = [];
+    for (const id of [...this.known].slice(0, VIEW.swarms)) {
+      const board = this.board.get(id) || { tasks: [], roles: [], truncated: false };
+      swarms.push({ id: short(id), ...(this.info.get(id) || {}), tasks: board.tasks.map(task => ({ ...task, ...(this.since.get(`${id}:${task.id}`) || { since: null, since_exact: false }) })), roles: board.roles, pending: this.pending.get(id) || [], plans: this.proposals.get(id) || [], criteria: this.criteria.get(id) || null, truncated: board.truncated || false });
+    }
+    return { swarms, swarms_total: this.known.size, updated_at: this.updatedAt };
+  }
+  /** Corta la espera en curso (cerrar la conexión cancela events.wait en relayd) y espera al bucle. */
+  async stop() { this.controller.abort(new Error('Watch stopped.')); this.connection?.close(); await this.loop?.catch(() => {}); this.state = 'stopped'; this.#changed(); }
+  #watched(swarm) { return typeof swarm === 'string' && (!this.filter || this.filter.has(swarm)); }
+  #error(where, error) { if (this.signal.aborted) return; this.lastError = { where, code: error.code || 'ERROR', message: String(error.message).slice(0, 600), at: new Date().toISOString() }; this.onError(this.lastError); this.#changed(); }
+  async #run() {
+    let backoff = 250;
+    while (!this.signal.aborted) {
+      let connection;
+      try {
+        this.#state('connecting');
+        connection = this.connection = await this.client.dedicated(this.signal); this.opened++;
+        backoff = 250;
+        if (this.cursor === null) { this.#state('catching_up'); await this.#catchUp(connection); }
+        this.lastError = null; if (this.state === 'waiting') this.#changed(); else this.#state('waiting');
+        await this.#follow(connection);
+      } catch (error) {
+        if (this.signal.aborted) return;
+        this.#error(this.state, error);
+        // Sin la capacidad read no hay nada que vigilar: hace falta otra delegación.
+        if (error.code === 'NOT_DELEGATED') { this.#state('stopped'); return; }
+        // Token ausente, revocado o vencido: espera larga (el humano lo reemite) sin martillar.
+        const wait = needsHuman(error) ? this.humanBackoffMs : backoff;
+        this.#state(needsHuman(error) ? 'needs_human' : 'backoff');
+        await sleep(wait, this.signal); backoff = Math.min(this.maxBackoffMs, backoff * 2);
+      } finally { connection?.close(); if (this.connection === connection) this.connection = null; }
+    }
+  }
+  /** Primera conexión: cursor = head_seq y revisión de lo que ya estaba pendiente. */
+  async #catchUp(connection) {
+    const { head_seq } = await connection.call('daemon.status', {}, { signal: this.signal });
+    const { swarms = [] } = await connection.call('swarm.list', {}, { signal: this.signal });
+    for (const swarm of swarms) if (this.#watched(swarm.id)) { this.known.add(swarm.id); this.#summary(swarm.id, swarm); }
+    for (const swarm of this.known) { await this.#status(connection, swarm); await this.#plans(connection, swarm); await this.#inbox(connection, swarm); }
+    await this.#jobs(connection);
+    this.cursor = String(head_seq ?? '0');
+  }
+  async #follow(connection) {
+    while (!this.signal.aborted) {
+      for (const notice of this.retry.splice(0)) await this.#send(notice);
+      const result = await connection.call('events.wait', { after: this.cursor, timeout_ms: String(this.waitMs), limit: this.batch }, { signal: this.signal, timeoutMs: this.waitMs + 15000 });
+      this.waits++;
+      const events = result?.events || [];
+      if (result?.timed_out || !events.length) continue;
+      await this.#apply(connection, events);
+      this.cursor = result.next_after || events.at(-1).seq || this.cursor;
+      this.#changed();
+    }
+  }
+  async #apply(connection, events) {
+    const statuses = new Set(), inboxes = new Set(), plans = new Set(), criteria = new Set(); let jobs = false;
+    for (const event of events) {
+      this.events++;
+      const [kind, id] = splitAggregate(event.aggregate_id);
+      this.lastEvent = { seq: event.seq, type: event.type, aggregate_id: event.aggregate_id, actor: event.actor, ...(event.via ? { via: event.via } : {}) };
+      if (event.type === 'swarm_created' && this.#watched(id)) { this.known.add(id); statuses.add(id); }
+      else if (event.type === 'message_sent') { const message = event.payload?.message; if (message?.to?.kind === 'operator' && this.#watched(message.swarm)) { this.known.add(message.swarm); inboxes.add(message.swarm); } }
+      else if (kind === 'task') { const swarm = this.taskSwarm.get(id); if (swarm) statuses.add(swarm); else for (const item of this.known) statuses.add(item); }
+      // Roles y equipos: ocupación y equipos del panel.
+      else if (kind === 'role' || kind === 'team') { const swarm = this.roleSwarm.get(id); if (swarm) statuses.add(swarm); else for (const item of this.known) statuses.add(item); }
+      // Ack o vencimiento de una entrega del operador: deja de estar pendiente en el panel.
+      else if (kind === 'delivery' && id.endsWith('@operator')) { const swarm = this.messageSwarm.get(id.slice(0, id.lastIndexOf('.'))); if (swarm) inboxes.add(swarm); else for (const item of this.known) inboxes.add(item); }
+      else if (kind === 'plan') plans.add(id);
+      // Revisor (open-relay F7): los criterios de éxito son eventos del swarm.
+      else if (kind === 'swarm' && /^criteria_/.test(event.type || '') && this.known.has(id)) criteria.add(id);
+      else if (kind === 'job') jobs = true;
+    }
+    for (const swarm of statuses) await this.#status(connection, swarm);
+    for (const swarm of criteria) if (!statuses.has(swarm)) await this.#criteria(connection, swarm);
+    for (const id of plans) {
+      try {
+        const got = await connection.call('plan.get', { proposal_id: id }, { signal: this.signal }), swarm = got?.proposal?.swarm_id;
+        if (!this.#watched(swarm)) continue;
+        // Revisor (F6): su plan de corrección se aprueba solo (nunca queda pendiente): se avisa al aplicarse.
+        const correction = correctionNotice(swarm, got.proposal); if (correction) await this.#send(correction);
+        await this.#plans(connection, swarm);
       }
-    })();
+      catch (error) { if (!error.rpc) throw error; this.#error(`plan:${id}`, error); }
+    }
+    for (const swarm of inboxes) await this.#inbox(connection, swarm);
+    if (jobs) await this.#jobs(connection);
   }
   /** Envía un aviso una sola vez por ref. Si el host no lo admite por ahora, queda para reintento. */
   async #send(notice) {
@@ -44,83 +145,95 @@ export class RelayWatcher {
     } else if (!this.retry.some(item => item.ref === notice.ref)) this.retry.push(notice);
     if (this.retry.length > 64) this.retry.shift();
   }
-  async #discover() {
-    for (const notice of this.retry.splice(0)) await this.#send(notice);
-    const { swarms = [] } = await this.client.call('swarm.list', {}, { signal: this.signal });
-    for (const swarm of swarms) {
-      if (typeof swarm.id !== 'string' || this.workers.has(swarm.id) || this.filter && !this.filter.has(swarm.id)) continue;
-      this.workers.set(swarm.id, [this.#follow(swarm.id, 'inbox', connection => this.#inbox(swarm.id, connection)), this.#follow(swarm.id, 'status', connection => this.#status(swarm.id, connection))]);
+  async #inbox(connection, swarm) {
+    let after = null; const pending = [];
+    for (let page = 0; page < 20; page++) {
+      const result = await connection.call('msg.inbox', { operator: true, swarm_id: swarm, pending_only: true, limit: PAGE, ...(after ? { after } : {}) }, { signal: this.signal });
+      for (const delivery of result.deliveries || []) if (delivery.state === 'pending') { await this.#delivery(connection, swarm, delivery); pending.push(delivery); }
+      if (!result.deliveries?.length || !result.next_after || result.next_after === after) break;
+      after = result.next_after;
     }
+    this.pending.set(swarm, pending.slice(-VIEW.pending).map(delivery => this.#pendingItem(swarm, delivery)));
   }
-  /** Una conexión dedicada por bucle; reconecta con espera creciente y relee el token. */
-  async #follow(swarm, name, body) {
-    let backoff = 250;
-    while (!this.signal.aborted) {
-      let connection;
-      try {
-        connection = await this.client.dedicated(this.signal); this.connections.add(connection);
-        backoff = 250; await body(connection);
-      } catch (error) {
-        if (this.signal.aborted) return;
-        this.#error(`${name}:${swarm}`, error);
-        if (error.rpc && !reconnectable(error) && error.code === 'INVALID_PARAMS') return; // swarm inexistente
-        await sleep(backoff, this.signal); backoff = Math.min(this.maxBackoffMs, backoff * 2);
-      } finally { connection?.close(); this.connections.delete(connection); }
-    }
+  /** Una entrega pendiente para el panel: quién, qué, desde cuándo y el bloque decision, limpios. */
+  #pendingItem(swarm, delivery) {
+    const message = delivery.message || {}, structured = decisionBlock(message);
+    if (typeof message.id === 'string') { this.messageSwarm.set(message.id, swarm); if (this.messageSwarm.size > SEEN_LIMIT) this.messageSwarm.delete(this.messageSwarm.keys().next().value); }
+    return {
+      delivery_id: short(delivery.delivery_id), message_id: short(message.id), kind: short(message.kind || 'message', 40),
+      from: message.from?.role ? `role:${short(message.from.role)}` : short(message.from?.kind || 'operator', 40),
+      sent_at: stamp(message.sent_at), excerpt: message.pruned ? null : excerpt(message.body || '', VIEW.excerpt),
+      task: this.questionTask.get(message.id) || null,
+      decision: structured ? { question: structured.question, options: structured.options.map(item => item.label), recommended: structured.recommendation?.option || null, scope: structured.scope, reversible: structured.reversible } : null,
+    };
   }
-  async #inbox(swarm, connection) {
-    if (!this.cursors.has(swarm)) {
-      // Primero las entregas pendientes que ya había (paginado), luego lo que llegue.
-      let after = 0n;
-      for (;;) {
-        const page = await connection.call('msg.inbox', { operator: true, swarm_id: swarm, after: String(after), limit: PAGE }, { signal: this.signal });
-        for (const delivery of page.deliveries || []) if (delivery.state === 'pending') await this.#delivery(swarm, delivery);
-        const next = page.next_after ? BigInt(page.next_after) : after;
-        if (!page.deliveries?.length || next === after) break;
-        after = next;
-      }
-      this.cursors.set(swarm, String(after));
-    }
-    while (!this.signal.aborted) {
-      const result = await connection.call('msg.wait', { operator: true, swarm_id: swarm, after: this.cursors.get(swarm), timeout_ms: String(this.waitMs) }, { signal: this.signal, timeoutMs: this.waitMs + 15000 });
-      for (const delivery of result.deliveries || []) if (delivery.state === 'pending') await this.#delivery(swarm, delivery);
-      if (result.next_after) this.cursors.set(swarm, result.next_after);
-    }
+  #summary(swarm, data = {}) {
+    const old = this.info.get(swarm) || {};
+    this.info.set(swarm, { objective: data.objective !== undefined ? excerpt(data.objective, VIEW.objective) : old.objective ?? null, root_team: data.root_team !== undefined ? short(data.root_team) : old.root_team ?? null });
   }
-  async #delivery(swarm, delivery) {
+  async #delivery(connection, swarm, delivery) {
     const ref = `delivery:${swarm}:${delivery.delivery_id}`;
     if (this.seen.has(ref)) return;
     let task = null;
     if (delivery.message?.kind === 'question' && delivery.message.from?.role) {
       // msg.ask bloquea la tarea en un commit posterior al envío: un margen breve.
-      task = await this.#blockedBy(swarm, delivery.message.id);
-      if (!task) { await sleep(this.questionGraceMs, this.signal); task = await this.#blockedBy(swarm, delivery.message.id); }
+      task = await this.#blockedBy(connection, swarm, delivery.message.id);
+      if (!task) { await sleep(this.questionGraceMs, this.signal); task = await this.#blockedBy(connection, swarm, delivery.message.id); }
     }
     await this.#send(deliveryNotice(delivery, { task }));
   }
-  async #blockedBy(swarm, messageId) {
+  async #blockedBy(connection, swarm, messageId) {
     try {
-      const status = await this.client.call('swarm.status', { swarm_id: swarm }, { signal: this.signal });
+      const status = await connection.call('swarm.status', { swarm_id: swarm }, { signal: this.signal });
       for (const task of (status.tasks || []).filter(item => item.state === 'blocked:question').slice(0, 20)) {
-        const detail = await this.client.call('task.get', { task_id: task.id }, { signal: this.signal });
-        if (detail.park?.reason?.kind === 'question' && detail.park.reason.message_id === messageId) return { id: task.id, state: task.state, title: task.title };
+        const detail = await connection.call('task.get', { task_id: task.id }, { signal: this.signal });
+        if (detail.park?.reason?.kind === 'question' && detail.park.reason.message_id === messageId) { this.questionTask.set(messageId, short(task.id)); return { id: task.id, state: task.state, title: task.title }; }
       }
-    } catch (error) { this.#error(`question:${swarm}`, error); }
+    } catch (error) { if (!error.rpc) throw error; this.#error(`question:${swarm}`, error); }
     return null;
   }
-  async #status(swarm, connection) {
-    while (!this.signal.aborted) {
-      const previous = this.digests.get(swarm);
-      const status = await connection.call('swarm.status', { swarm_id: swarm, ...(previous ? { if_changed: previous, timeout_ms: String(this.waitMs) } : {}) }, { signal: this.signal, timeoutMs: this.waitMs + 15000 });
-      if (previous && status.changed === false) continue;
-      this.digests.set(swarm, status.digest);
-      for (const task of status.tasks || []) { const alert = taskAlert(swarm, task); if (alert) await this.#send(alert); }
-      const plans = await connection.call('plan.list', { swarm_id: swarm, status: 'pending' }, { signal: this.signal });
-      for (const proposal of plans.proposals || []) if (proposal.status === 'pending') await this.#send(planNotice(swarm, proposal));
-    }
+  /** Foto del swarm: estados de tareas (para status()) y alertas de infraestructura. */
+  async #status(connection, swarm) {
+    let status;
+    try { status = await connection.call('swarm.status', { swarm_id: swarm }, { signal: this.signal }); }
+    catch (error) { if (!error.rpc) throw error; this.#error(`status:${swarm}`, error); return; }
+    const states = new Map(), previous = this.taskStates.get(swarm), first = previous === undefined, at = this.now();
+    for (const task of status.tasks || []) { if (typeof task.id !== 'string') continue; states.set(task.id, task.state); this.taskSwarm.set(task.id, swarm); }
+    // Desde cuándo se ve cada estado: exacto si el cambio llegó por un evento; en la primera
+    // foto sólo se sabe que ya estaba así («al menos»).
+    for (const [task, state] of states) if (previous?.get(task) !== state || !this.since.has(`${swarm}:${task}`)) this.since.set(`${swarm}:${task}`, { since: at, since_exact: !first });
+    for (const task of previous?.keys() || []) if (!states.has(task)) this.since.delete(`${swarm}:${task}`);
+    this.taskStates.set(swarm, states);
+    if (status.swarm) this.#summary(swarm, status.swarm);
+    const roles = Array.isArray(status.roles) ? status.roles : [], tasks = Array.isArray(status.tasks) ? status.tasks : [];
+    for (const role of roles) if (typeof role?.id === 'string') this.roleSwarm.set(role.id, swarm);
+    for (const role of roles) if (typeof role?.team === 'string') this.roleSwarm.set(role.team, swarm);
+    const names = new Map(roles.map(role => [role?.id, role?.name]));
+    this.board.set(swarm, {
+      truncated: tasks.length > VIEW.tasks || roles.length > VIEW.roles,
+      tasks: tasks.filter(task => typeof task?.id === 'string').slice(0, VIEW.tasks).map(task => ({ id: short(task.id), title: task.title ? excerpt(task.title, VIEW.title) : null, state: short(task.state, 40), team: short(task.team), role: short(task.required_role), role_name: names.get(task.required_role) ? short(names.get(task.required_role), 60) : null, attempts_used: Number(task.attempts_used) || 0, counted_attempts: task.counted_attempts == null ? Number(task.attempts_used) || 0 : Number(task.counted_attempts) || 0, max_attempts: Number(task.max_attempts) || 0, ...(task.infra?.exhausted ? { infra_exhausted: true } : {}), ...(task.wake_cap === true ? { wake_cap: true } : {}), ...(Number(task.review_rounds) > 0 ? { review_rounds: Number(task.review_rounds) } : {}), ...(['task', 'integration', 'final'].includes(task.review_kind) ? { review_kind: task.review_kind } : {}) })),
+      roles: roles.slice(0, VIEW.roles).map(role => ({ id: short(role.id), name: short(role.name || role.id, 60), team: short(role.team), occupied: Boolean(role.occupant), load: Number(role.load) || 0, capacity: Number(role.capacity) || 0, model: role.model ? short(role.model, 60) : null })),
+    });
+    for (const task of status.tasks || []) { const alert = taskAlert(swarm, task) || reviewAlert(swarm, task); if (alert) await this.#send(alert); }
+    // Revisor (open-relay F7): un swarm con revisor tiene criterios de éxito que acepta el humano.
+    if (tasks.some(task => /^t-review/.test(task?.id || ''))) await this.#criteria(connection, swarm);
+  }
+  async #criteria(connection, swarm) {
+    try {
+      const got = await connection.call('criteria.get', { swarm_id: swarm }, { signal: this.signal });
+      this.criteria.set(swarm, { status: short(got?.status || 'none', 20), version: Number(got?.current?.version) || 0, digest: /^[a-f0-9]{64}$/.test(String(got?.current?.digest || '')) ? got.current.digest : null, rounds: Number(got?.rounds) || 0, renegotiating: Boolean(got?.accepted), in_force: Number(got?.accepted?.version) || 0 });
+    } catch (error) { if (!error.rpc) throw error; this.#error(`criteria:${swarm}`, error); }
+  }
+  async #plans(connection, swarm) {
+    const plans = await connection.call('plan.list', { swarm_id: swarm, status: 'pending' }, { signal: this.signal });
+    // Revisor (open-relay F3/F8): un plan que espera al revisor todavía no es decidible por el
+    // humano (relayd respondería REVIEW_PENDING): no hay aviso ni tarjeta hasta que lo revise.
+    const pending = (plans.proposals || []).filter(proposal => proposal.status === 'pending' && proposal.review?.status !== 'awaiting');
+    for (const proposal of pending) await this.#send(planNotice(swarm, proposal));
+    this.proposals.set(swarm, pending.slice(0, VIEW.plans).map(proposal => ({ proposal_id: short(proposal.proposal_id), proposer_role: short(proposal.proposer_role), parent_task: proposal.parent_task ? short(proposal.parent_task) : null, summary: excerpt(proposal.summary || '', VIEW.excerpt), proposed_at: stamp(proposal.proposed_at), tasks: Number(proposal.tasks) || 0, roles: Number(proposal.roles) || 0 })));
   }
-  async #jobs() {
-    const result = await this.client.call('job.list', {}, { signal: this.signal });
+  async #jobs(connection) {
+    const result = await connection.call('job.list', {}, { signal: this.signal });
     if (!result.available) return;
     for (const job of result.jobs || []) { const alert = jobAlert(job); if (alert) await this.#send(alert); }
   }

package/src/plugins.mjs

@@ -33,6 +33,7 @@ export class PluginRuntime {
   #services = new Map();
   #queue = Promise.resolve();
   #closing = false;
+  #serviceWatchers = new Set();
   // notify(notice): el host encola avisos de plugins (plugin-notices.mjs); sin él, ctx.notify responde unavailable.
   constructor({ cwd, house, services = {}, configPath, onEvent = () => {}, notify }) {
     Object.assign(this, { cwd, house, onEvent, notify });
@@ -41,7 +42,16 @@ export class PluginRuntime {
   }
   async #notify(notice) { if (typeof this.notify !== 'function') return { status: 'unavailable' }; try { return await this.notify(notice); } catch (error) { return { status: 'failed', error: String(error.message).slice(0, 200) }; } }
   #exclusive(task) { const next = this.#queue.catch(() => {}).then(task); this.#queue = next; return next; }
-  async #event(event) { try { await this.onEvent({ type: 'plugin_status', ...event }); } catch {} }
+  async #event(event) { try { await this.onEvent({ type: 'plugin_status', ...event }); } catch {} this.#servicesChanged(); }
+  #servicesChanged() { for (const listener of [...this.#serviceWatchers]) try { listener(); } catch {} }
+  /**
+   * Lectura del HOST de un servicio publicado (ctx.provide), p. ej. para un panel de la TUI.
+   * Devuelve { owner, value } o null; el host debe comprobar el dueño y tratar los datos
+   * como no confiables. No concede nada al plugin ni al modelo.
+   */
+  service(name) { const entry = this.#services.get(name); return entry ? Object.freeze({ owner: entry.owner, value: entry.value }) : null; }
+  /** Avisa (sin argumentos) cuando cambia el estado de los plugins o sus servicios. Devuelve la baja. */
+  watchServices(listener) { if (typeof listener !== 'function') throw new TypeError('watchServices requires a function.'); this.#serviceWatchers.add(listener); return () => this.#serviceWatchers.delete(listener); }
   #definition(definition) {
     if (!definition || !idPattern.test(definition.id) || definition.id.length > 24 || typeof definition.version !== 'string' || !definition.version || typeof definition.activate !== 'function') throw new Error('Manifiesto de plugin inválido: requiere id, version y activate.');
     const names = list => { if (!Array.isArray(list) || list.length > 32 || list.some(name => typeof name !== 'string' || !name || name.length > 128) || new Set(list).size !== list.length) throw new Error('requires/provides de plugin inválidos.'); return [...list]; };
@@ -309,6 +319,7 @@ export class PluginRuntime {
       this.house.registry.replace(scopes.flatMap(scope => [...scope.operations.keys()]), []);
       for (const scope of scopes) { this.#known.get(scope.id).state = 'disabled'; try { await this.#retire(scope); } catch (error) { errors.push(error); } }
       for (const [name, service] of this.#services) if (service.owner !== 'host') this.#services.delete(name);
+      this.#servicesChanged(); this.#serviceWatchers.clear();
       if (errors.length) throw new AggregateError(errors, 'Falló limpieza de plugins.');
     });
   }

package/src/process-lock.mjs

@@ -1,5 +1,5 @@
 import { constants, readFileSync, readlinkSync } from 'node:fs';
-import { open, lstat, unlink } from 'node:fs/promises';
+import { open, lstat, unlink, link } from 'node:fs/promises';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -18,6 +18,7 @@ export function processDead(owner) {
   const current=start(owner.pid);
   return Boolean(owner.start && current && owner.start!==current);
 }
+const STALE_EMPTY_MS = 30000;
 const fail = (message,code='SESSION_IN_USE') => Object.assign(new Error(message),{code});
 async function inspect(name,fault=async()=>{}) {
   const named=await lstat(name,{bigint:true});if(named.isSymbolicLink()||!named.isFile())throw fail('Unsafe lock type; no lock was removed.','LOCK_UNSAFE');
@@ -34,6 +35,9 @@ async function inspect(name,fault=async()=>{}) {
     if(!await same(name,info))throw fail('Lock changed during private inspection; no owner was assumed.','LOCK_CHANGED');
     const bytes=Buffer.alloc(4097),{bytesRead}=await file.read(bytes,0,bytes.length,0);if(bytesRead>4096)throw fail('Lock exceeds its owner-record bound.','LOCK_UNSAFE');
     const text=bytes.subarray(0,bytesRead).toString('utf8').trim();let owner;
+    // An empty lock is a writer that died between creating the file and writing its owner
+    // (older Comal created first and wrote later). Fresh, it may still be mid-write; stale, nobody owns it.
+    if(!text && Date.now()-Number(info.mtimeMs)>STALE_EMPTY_MS){if(!await same(name,info))throw fail('Lock changed while reading its owner; no owner was assumed.','LOCK_CHANGED');return {info,owner:{empty:true}};}
     try{owner=JSON.parse(text);}catch{throw fail('Lock sin propietario verificable; no se retiró.','LOCK_UNKNOWN');}
     if(typeof owner==='number')owner={pid:owner}; // Legacy PID: only ESRCH proves death.
     if(!owner || !Number.isSafeInteger(owner.pid) || owner.pid<=0)throw fail('Lock sin propietario verificable; no se retiró.','LOCK_UNKNOWN');
@@ -43,39 +47,43 @@ async function inspect(name,fault=async()=>{}) {
 }
 async function same(name,info){try{const current=await lstat(name,{bigint:true});return !current.isSymbolicLink() && current.ino===info.ino && current.dev===info.dev;}catch(e){if(e.code==='ENOENT')return false;throw e;}}
 
+// Claim `name` with its owner record already written: the record goes to a private temporary
+// file that is then hard-linked into place, so the lock path never exists empty. null if held.
+async function claim(name,owner){
+  const temp=`${name}.${owner.token}.tmp`,file=await open(temp,'wx',0o600);
+  try{await file.writeFile(JSON.stringify(owner));await file.sync();await link(temp,name);}
+  catch(error){await file.close();await unlink(temp).catch(()=>{});if(error.code==='EEXIST')return null;throw error;}
+  await unlink(temp);return file;
+}
+
 // Only this exclusion gate may reclaim a dead owner. It is never automatically
 // reclaimed itself: two reapers must not unlink a replacement lock concurrently.
 export async function acquireProcessLock(name,{waitMs=0,validate=async()=>{},resource,fault=async()=>{}}={}) {
   const until=Date.now()+waitMs;
   for(;;){
-    let file, recovered;
-    try{file=await open(name,'wx',0o600);}
-    catch(error){
-      if(error.code!=='EEXIST')throw error;
+    let recovered;const owner={...processIdentity,token:randomUUID(),...(resource?{resource:structuredClone(resource)}:{})};
+    let file=await claim(name,owner);
+    if(!file){
       let old;
       try{old=await inspect(name,fault);}catch(e){if(e.code==='ENOENT')continue;if(['LOCK_UNKNOWN','LOCK_CHANGED'].includes(e.code)&&Date.now()<until){await delay(10);continue;}if(e.code==='LOCK_CHANGED')throw fail('The lock changed during observation; no owner was assumed or removed.');throw e;}
-      if(processDead(old.owner)){
+      if(old.owner.empty || processDead(old.owner)){
         let gate;
         try{gate=await open(`${name}.reclaim`,'wx',0o600);}
         catch(e){if(e.code!=='EEXIST')throw e;if(Date.now()>=until)throw fail('Recuperación de lock en uso o interrumpida; no se retiró.','LOCK_RECOVERY_BUSY');}
         if(gate)try{
           await gate.writeFile(JSON.stringify(processIdentity));await gate.sync();
           const current=await inspect(name,fault).catch(e=>{if(['ENOENT','LOCK_CHANGED'].includes(e.code))return null;throw e;});
-          if(current && processDead(current.owner) && await same(name,current.info)){
+          if(current && (current.owner.empty || processDead(current.owner)) && await same(name,current.info)){
             await validate(current.owner);
             if(await same(name,current.info)){
               await unlink(name);
-              try{file=await open(name,'wx',0o600);recovered={path:name,owner:current.owner};}
-              catch(e){if(e.code!=='EEXIST')throw e;}
+              file=await claim(name,owner);if(file)recovered={path:name,owner:current.owner};
             }
           }
         } finally{const info=await gate.stat({bigint:true});if(await same(`${name}.reclaim`,info))await unlink(`${name}.reclaim`);await gate.close();}
       }
       if(!file){if(Date.now()>=until)throw fail('Sesión en uso o propietario no recuperable; no se retiró el lock.');await delay(10);continue;}
     }
-    const owner={...processIdentity,token:randomUUID(),...(resource?{resource:structuredClone(resource)}:{})};
-    try{await file.writeFile(JSON.stringify(owner));await file.sync();}
-    catch(error){const info=await file.stat({bigint:true});if(await same(name,info))await unlink(name);await file.close();throw error;}
     return {file,recovered,release:async()=>{const info=await file.stat({bigint:true});try{if(await same(name,info))await unlink(name);}finally{await file.close();}}};
   }
 }

package/src/provider-auth.mjs

@@ -13,14 +13,17 @@ export const AUTH_PROVIDERS = Object.freeze([
   { id: 'grok', label: 'Grok / xAI API', method: 'api_key', subscription: false, protocol: 'openai', baseURL: 'https://api.x.ai/v1', apiKeyEnv: 'XAI_API_KEY', documentation: 'https://docs.x.ai/overview' },
   // Ollama Cloud expone una API compatible con OpenAI en /v1 y /api/show para
   // descubrir la ventana. La llave sólo viaja en el header hacia ese origen.
-  { id: 'ollama', label: 'Ollama Cloud', method: 'api_key', subscription: false, protocol: 'openai', baseURL: 'https://ollama.com/', apiKeyEnv: 'OLLAMA_API_KEY', documentation: 'https://docs.ollama.com/cloud' }
+  { id: 'ollama', label: 'Ollama Cloud', method: 'api_key', subscription: false, protocol: 'openai', baseURL: 'https://ollama.com/', apiKeyEnv: 'OLLAMA_API_KEY', documentation: 'https://docs.ollama.com/cloud' },
+  // Anthropic API (Claude): llave de la Console, facturación por API. /v1/models lista
+  // los modelos y /v1/models/{id} anuncia ventana, salida máxima y niveles de effort.
+  { id: 'anthropic', label: 'Anthropic API (Claude)', method: 'api_key', subscription: false, protocol: 'anthropic', baseURL: 'https://api.anthropic.com', model: 'claude-sonnet-5-5', apiKeyEnv: 'ANTHROPIC_API_KEY', documentation: 'https://docs.claude.com/en/api/overview' }
 ].map(Object.freeze));
-const ALIASES = Object.freeze({ grokia: 'grok', xai: 'grok', chatgpt: 'codex', 'kimi-code': 'kimi', 'ollama-cloud': 'ollama' });
+const ALIASES = Object.freeze({ grokia: 'grok', xai: 'grok', chatgpt: 'codex', 'kimi-code': 'kimi', 'ollama-cloud': 'ollama', claude: 'anthropic' });
 const failure = (message, code = 'PROVIDER_AUTH_FAILED') => Object.assign(new Error(message), { code });
 function definition(name) {
   const id = String(name || '').toLowerCase();
   const found = AUTH_PROVIDERS.find(item => item.id === (Object.hasOwn(ALIASES, id) ? ALIASES[id] : id));
-  if (!found) throw failure('Unknown login provider: codex, kimi, minimax, grok or ollama.', 'PROVIDER_AUTH_UNKNOWN');
+  if (!found) throw failure('Unknown login provider: codex, kimi, minimax, grok, ollama or anthropic.', 'PROVIDER_AUTH_UNKNOWN');
   return found;
 }
 export function authProviderDefinition(name) { return definition(name); }

package/src/provider-profiles.mjs

@@ -1,3 +1,4 @@
+import { registerSecretEnv } from './child-env.mjs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { OpenAIProvider, DEFAULT_LOCAL_URL } from './openai-provider.mjs';
@@ -5,11 +6,12 @@ import { AnthropicProvider } from './provider.mjs';
 import { GeminiProvider } from './gemini-provider.mjs';
 import { authProviderDefaults } from './provider-auth.mjs';
 import { normalizeEffort } from './model-controls.mjs';
+import { normalizeFallbackSetting } from './provider.mjs';
 import {normalizeToolSchemaCapabilities} from './tool-schema.mjs';
 
 export const PROVIDER_CAPABILITIES = Object.freeze(['text', 'tools', 'thinking', 'vision', 'video', 'web_search']);
 const PROTOCOLS = ['openai', 'anthropic', 'gemini'];
-const KEYS = new Set(['name', 'provider', 'protocol', 'model', 'baseURL', 'apiKeyEnv', 'capabilities', 'capabilitiesConfigured', 'description', 'effort', 'authProvider','toolSchema']);
+const KEYS = new Set(['name', 'provider', 'protocol', 'model', 'baseURL', 'apiKeyEnv', 'capabilities', 'capabilitiesConfigured', 'description', 'effort', 'authProvider','toolSchema', 'maxTokens', 'contextWindow', 'fallback']);
 const error = message => Object.assign(new Error(message), { code: 'PROVIDER_PROFILE_INVALID' });
 
 export function normalizeCapabilities(value = {}, { protocol = 'openai' } = {}) {
@@ -31,6 +33,7 @@ export function normalizeProviderProfile(input, name = input?.name) {
   if (input.name && input.name !== name) throw error('Conflicting profile name.');
   if (input.authProvider !== undefined && !['codex', 'kimi', 'minimax', 'grok'].includes(input.authProvider)) throw error('Invalid authProvider.');
   if (input.effort !== undefined) normalizeEffort(input.effort);
+  if (input.fallback !== undefined) normalizeFallbackSetting(input.fallback);
   const toolSchema=input.toolSchema===undefined?undefined:normalizeToolSchemaCapabilities(input.toolSchema);
   const access=input.authProvider?authProviderDefaults(input.authProvider):null;
   const configuredCapabilities = input.capabilitiesConfigured || input.capabilities || {};
@@ -47,11 +50,17 @@ export function normalizeProviderProfile(input, name = input?.name) {
   }
   if (input.apiKeyEnv !== undefined && (typeof input.apiKeyEnv !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(input.apiKeyEnv))) throw error('apiKeyEnv must name an environment variable.');
   if (input.description !== undefined && (typeof input.description !== 'string' || input.description.length > 1024)) throw error('Invalid description.');
+  // Output and window budgets are startup defaults for this endpoint; --max-tokens,
+  // --context-window, their variables and connection.json still win.
+  if (input.maxTokens !== undefined && (!Number.isSafeInteger(input.maxTokens) || input.maxTokens < 64 || input.maxTokens > 1000000)) throw error('maxTokens must be an integer between 64 and 1000000.');
+  if (input.contextWindow !== undefined && (!Number.isSafeInteger(input.contextWindow) || input.contextWindow < 4096 || input.contextWindow > 2000000)) throw error('contextWindow must be an integer between 4096 and 2000000.');
+  if (input.maxTokens !== undefined && input.contextWindow !== undefined && input.contextWindow < input.maxTokens * 2) throw error('contextWindow must be at least twice maxTokens.');
   return Object.freeze({ name, provider: protocol, protocol, ...((input.model || access?.model) ? { model: input.model || access.model } : {}),
     baseURL: input.baseURL || access?.baseURL || ({ openai: DEFAULT_LOCAL_URL, anthropic: 'https://api.anthropic.com', gemini: 'https://generativelanguage.googleapis.com/v1beta' })[protocol],
     apiKeyEnv: input.apiKeyEnv || ({ openai: 'OPENAI_API_KEY', anthropic: 'ANTHROPIC_API_KEY', gemini: 'GEMINI_API_KEY' })[protocol],
     capabilities: normalizeCapabilities(input.capabilities, { protocol }), capabilitiesConfigured: Object.freeze({ ...configuredCapabilities }),...(toolSchema?{toolSchema:Object.freeze(toolSchema)}:{}),
-    ...(input.effort !== undefined ? { effort: input.effort } : {}), ...(input.authProvider ? { authProvider: input.authProvider } : {}), ...(input.description ? { description: input.description } : {}) });
+    ...(input.effort !== undefined ? { effort: input.effort } : {}), ...(input.authProvider ? { authProvider: input.authProvider } : {}), ...(input.description ? { description: input.description } : {}),
+    ...(input.maxTokens !== undefined ? { maxTokens: input.maxTokens } : {}), ...(input.contextWindow !== undefined ? { contextWindow: input.contextWindow } : {}), ...(input.fallback !== undefined ? { fallback: input.fallback } : {}) });
 }
 
 // Configuration is data only. Secrets are resolved in createProfileProvider and
@@ -92,11 +101,12 @@ export function selectProfile(registry, name) {
 
 export function createProfileProvider(profile, { env = process.env, ...overrides } = {}) {
   profile = normalizeProviderProfile(profile);
+  registerSecretEnv(profile.apiKeyEnv);
   const capabilities = { ...profile.capabilities };
   if (overrides.vision === 'on') capabilities.vision = true;
   else if (overrides.vision === 'off') capabilities.vision = false;
   const options = { ...overrides, apiKey: overrides.apiKey ?? env[profile.apiKeyEnv], model: overrides.model || profile.model, baseURL: overrides.baseURL || profile.baseURL,
-    capabilities, capabilitiesConfigured: profile.capabilitiesConfigured, effort: overrides.effort ?? profile.effort ?? 'auto', vision: overrides.vision || (Object.hasOwn(profile.capabilitiesConfigured, 'vision') ? capabilities.vision ? 'on' : 'off' : 'auto') };
+    capabilities, capabilitiesConfigured: profile.capabilitiesConfigured, effort: overrides.effort ?? profile.effort ?? 'auto', fallback: overrides.fallback ?? profile.fallback ?? 'default', vision: overrides.vision || (Object.hasOwn(profile.capabilitiesConfigured, 'vision') ? capabilities.vision ? 'on' : 'off' : 'auto') };
   if (profile.protocol !== 'openai' && !options.apiKey) throw new Error(`Set the profile apiKeyEnv variable ${profile.apiKeyEnv}.`);
   const provider = profile.protocol === 'gemini' ? new GeminiProvider(options) : profile.protocol === 'anthropic' ? new AnthropicProvider(options) : new OpenAIProvider(options);
   const complete = provider.complete.bind(provider);