@milpa/comal 0.2.1 → 0.2.3

package/src/remote-relay.mjs

@@ -0,0 +1,468 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { line, criteriaWaiting, criteriaWarnings, warningSummary } from './relay/cards.mjs';
+import { swarmFinished, blockedForOperator, blockedKey, blockedReason } from './relay/follow.mjs';
+import { decisionBlock } from './plugins/open-relay/decision.mjs';
+import { normalizeSwarmView, swarmColumn, SWARM_COLUMNS } from './tui/swarm-panel.mjs';
+
+// /rc + /relay: proyección del tablero de /swarm y de las tarjetas de /relay hacia el navegador
+// de Remote Control (fase «ver») y la marca de qué tarjetas puede responder (fase «responder»).
+// Es una proyección, no autoridad: ningún evento relay.* habilita nada. Las respuestas del
+// navegador llegan como controles tipados (remote-relay-answers-v1.json) que el host revalida
+// y aplica con las mismas funciones que la TUI (src/relay/broker.mjs). Contrato de eventos:
+// backend/contracts/remote-relay-v1.schema.json (aditivo: criteria, escalation y la columna
+// reviewing sólo salen hacia un backend que admite relay_answers_v1).
+//
+// Lista blanca, nunca copia de la foto del panel: no salen control_dir, issue_command,
+// tokenFile, la raíz del hub, el repo absoluto (sólo su nombre base), la UI local de relayd,
+// el diff, las capturas ni el diseño. El texto de los agentes no es confiable: se limpia con
+// el line() de las tarjetas, se le quitan rutas de casa, direcciones de loopback y cosas con
+// forma de secreto, se acota y viaja marcado `untrusted`; el navegador lo pinta con textContent.
+
+export const RELAY_EVENT_BYTES = 36000;          // por evento, bajo el techo de 48 KiB con sobre
+export const RELAY_PLAN_PAGES = 5;               // relay.card + ≤ 4 relay.card.page
+export const RELAY_BOARD_TASKS = 40;             // tareas con detalle en el tablero (en total)
+export const RELAY_BOARD_SWARMS = 4;             // enjambres con detalle en el tablero
+export const RELAY_SESSION_EVENTS = 2000;        // presupuesto por sesión de /rc
+export const RELAY_SESSION_BYTES = 16 << 20;
+export const RELAY_BOARD_INTERVAL_MS = 3000;     // tablero coalescido
+
+const sha256 = value => createHash('sha256').update(value).digest('hex');
+/** Contrato navegador → host de /relay (acciones, campos, texto, capacidades y step-up). */
+export const RELAY_ANSWERS = JSON.parse(readFileSync(new URL('../backend/contracts/remote-relay-answers-v1.json', import.meta.url), 'utf8'));
+const SAFE = Object.fromEntries(['project', 'swarm', 'subject'].map(field => [field, new RegExp(RELAY_ANSWERS.control.properties[field].pattern)]));
+export const relayBytes = value => Buffer.byteLength(JSON.stringify(value));
+
+// Lo que nunca debe salir aunque lo escriba un agente: rutas de casa, loopback con puerto y
+// formas típicas de credencial (relayd orly_, claves de proveedores, bearer).
+const REDACTIONS = [
+  [/(?:\/home|\/Users)\/[^/\s'"`»«)]+/g, '~'],
+  [/(?<![\w.-])\/root(?=\/)/g, '~'],
+  [/\borly_[A-Za-z0-9_-]{4,}/g, '[redacted]'],
+  [/\b(?:sk|rk|pk)-[A-Za-z0-9_-]{16,}/g, '[redacted]'],
+  [/\bgh[pousr]_[A-Za-z0-9]{16,}/g, '[redacted]'],
+  [/\bxox[abprs]-[A-Za-z0-9-]{10,}/g, '[redacted]'],
+  [/\bAKIA[0-9A-Z]{16}\b/g, '[redacted]'],
+  [/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi, 'Bearer [redacted]'],
+  [/\b(?:https?:\/\/)?(?:127(?:\.\d{1,3}){3}|localhost|\[::1\]|0\.0\.0\.0)(?::\d{1,5})?(?:\/\S*)?/gi, '[local address]'],
+];
+/** Texto ajeno: sin secretos con forma conocida, limpio (line) y acotado a `limit` caracteres. */
+export function scrub(value, limit) {
+  let text = String(value ?? '');
+  for (const [pattern, replacement] of REDACTIONS) text = text.replace(pattern, replacement);
+  return line(text, limit);
+}
+const txt = (value, limit) => scrub(value, limit);
+const opt = (value, limit) => { const text = value == null ? '' : scrub(value, limit); return text || null; };
+const int = value => { const n = Number(value); return Number.isFinite(n) && n >= 0 ? Math.min(Math.floor(n), 2 ** 31 - 1) : 0; };
+const time = value => { const n = Number(value); return Number.isFinite(n) && n > 0 ? Math.floor(n) : null; };
+const hex = (value, size) => { const text = String(value || '').toLowerCase(); return new RegExp(`^[a-f0-9]{${size}}$`).test(text) ? text : null; };
+
+/** Identidad estable de una tarjeta: el mismo plan re-propuesto (otro digest) es otra tarjeta. */
+export const relayCardId = (project, swarm, kind, subject, version = '') => sha256(JSON.stringify(['relay-card/1', project || '', swarm || '', kind, subject || '', version || ''])).slice(0, 32);
+/** Etiqueta de una opción tal como la ve el navegador (el host compara su sha256). */
+export const relayOptionLabel = label => scrub(label, 120);
+/**
+ * ¿Puede el navegador responder esta tarjeta? Sólo las clases del contrato de respuestas, sólo
+ * hacia un backend con relay_answers_v1, sólo con ids que el control admite (sin rutas) y sólo
+ * las acciones cuyas capacidades tiene la delegación (null = desconocidas: decide relayd). El
+ * armado local (/rc relay on) no va aquí: el navegador lo ve en vivo en el estado de la sesión
+ * y el host lo vuelve a comprobar al reclamar cada control.
+ */
+export function relayAnswerable(kind, { answers = false, caps = null, ids = {} } = {}) {
+  const names = Object.entries(RELAY_ANSWERS.actions).filter(([, action]) => action.card === kind).map(([name]) => name);
+  if (!names.length) return { browser: false, why: 'terminal_only' };
+  if (!answers) return { browser: false, why: 'host_legacy' };
+  if (!Object.entries(ids).every(([field, value]) => SAFE[field].test(String(value ?? '')))) return { browser: false, why: 'terminal_only' };
+  const actions = Array.isArray(caps) ? names.filter(name => RELAY_ANSWERS.actions[name].caps.every(cap => caps.includes(cap))) : names;
+  return actions.length ? { browser: true, actions } : { browser: false, why: 'cap_missing' };
+}
+
+// ── Tablero ────────────────────────────────────────────────────────────────
+const PRIORITY = ['blocked', 'running', 'reviewing', 'verifying', 'pending', 'other', 'done', 'closed'];
+// La columna «en revisión» de /swarm (revisor, open-relay F7) es aditiva en el contrato: sólo
+// sale hacia un backend que la admite (relay_answers_v1); hacia uno anterior cuenta como
+// `verifying` y la tarea conserva su estado real (`reviewing`).
+const columnsFor = reviewing => SWARM_COLUMNS.filter(column => reviewing || column !== 'reviewing');
+
+/** Tablero de /swarm para el navegador: ≤ 4 enjambres con detalle y ≤ 40 tareas, ≤ 36.000 B. */
+export function projectRelayBoard(view, { project = null, repo = null, at = Date.now(), reviewing = false } = {}) {
+  const v = normalizeSwarmView(view);
+  const rcColumn = state => { const column = swarmColumn(state); return column === 'reviewing' && !reviewing ? 'verifying' : column; };
+  const emptyCounts = () => Object.fromEntries(columnsFor(reviewing).map(column => [column, 0]));
+  const base = { shape: 'board', version: 1, project: opt(project, 60), repo_name: repo ? opt(path.basename(String(repo)), 120) : null };
+  if (!v?.available) return { ...base, available: false, reason: txt(v?.reason || 'unavailable', 40), connection: null, swarms: [], swarms_total: 0, pending: { plans: 0, questions: 0, blocked: 0 }, omitted: { swarms: 0, tasks: 0 }, source: { view_generated_at: time(at) || 1 } };
+  const c = v.connection || {};
+  const connection = { state: txt(c.state || 'idle', 30), mode: ['cards', 'on', 'off'].includes(c.mode) ? c.mode : 'on', caps: (c.delegate?.caps || []).slice(0, 12).map(cap => txt(cap, 30)), missing_caps: (c.missing_caps || []).slice(0, 8).map(cap => txt(cap, 30)) };
+  const all = v.swarms.map(swarm => {
+    const counts = emptyCounts();
+    for (const task of swarm.tasks) counts[rcColumn(task.state)]++;
+    const plans = swarm.plans.filter(plan => plan.proposal_id).length, questions = swarm.pending.filter(item => item.kind === 'question' && item.message_id).length;
+    return { swarm, counts, plans, questions, open: swarm.tasks.length - counts.done - counts.closed };
+  });
+  const pending = { plans: 0, questions: 0, blocked: 0 };
+  for (const item of all) { pending.plans += item.plans; pending.questions += item.questions; pending.blocked += item.counts.blocked; }
+  // Primero lo que espera al humano, luego lo que sigue abierto; el orden del panel desempata.
+  const ranked = all.map((item, index) => ({ ...item, index })).sort((a, b) => (b.plans + b.questions > 0) - (a.plans + a.questions > 0) || (b.open > 0) - (a.open > 0) || a.index - b.index).slice(0, RELAY_BOARD_SWARMS);
+  let room = RELAY_BOARD_TASKS, omittedTasks = 0;
+  const swarms = ranked.map((item, position) => {
+    const share = Math.max(0, Math.ceil(room / (ranked.length - position)));
+    const sorted = [...item.swarm.tasks].sort((a, b) => PRIORITY.indexOf(rcColumn(a.state)) - PRIORITY.indexOf(rcColumn(b.state)));
+    const shown = sorted.slice(0, share); room -= shown.length; omittedTasks += sorted.length - shown.length;
+    return {
+      id: txt(item.swarm.id, 120), objective: opt(item.swarm.objective, 300), counts: item.counts, tasks_total: item.swarm.tasks.length,
+      pending: { plans: item.plans, questions: item.questions },
+      tasks: shown.map(task => ({ id: txt(task.id, 120), title: opt(task.title, 160), state: txt(task.state, 40), column: rcColumn(task.state), role: opt(task.role_name || task.role, 60), attempts_used: int(task.counted_attempts ?? task.attempts_used), max_attempts: int(task.max_attempts), since: time(task.since), infra_exhausted: task.infra_exhausted === true })),
+    };
+  });
+  const board = { ...base, available: true, connection, swarms, swarms_total: Math.max(int(v.swarms_total), all.length), pending, omitted: { swarms: Math.max(0, all.length - swarms.length) + Math.max(0, int(v.swarms_total) - all.length), tasks: omittedTasks }, source: { view_generated_at: time(v.generated_at) || time(at) || 1 } };
+  // Por bytes, nunca por número: se quitan tareas enteras del enjambre con más, luego enjambres.
+  while (relayBytes(board) > RELAY_EVENT_BYTES) {
+    const widest = board.swarms.reduce((best, swarm) => !best || swarm.tasks.length > best.tasks.length ? swarm : best, null);
+    if (widest?.tasks.length) { widest.tasks.pop(); board.omitted.tasks++; }
+    else if (board.swarms.length) { const dropped = board.swarms.pop(); board.omitted.swarms++; board.omitted.tasks += dropped.tasks.length; }
+    else break;
+  }
+  return board;
+}
+/** Huella del tablero sin su sello de tiempo: dos fotos iguales no generan dos eventos. */
+export const relayBoardDigest = board => { const { source, ...content } = board || {}; return sha256(JSON.stringify(content)); };
+
+// ── Tarjetas ───────────────────────────────────────────────────────────────
+const TERMINAL_ONLY = Object.freeze({ browser: false, why: 'terminal_only' });
+const envelope = ({ project, swarm, kind, subject, version, step_up = 'none', answerable = TERMINAL_ONLY }) => ({
+  shape: 'card', version: 1, card_id: relayCardId(project, swarm, kind, subject, version), kind, state: 'pending',
+  project: txt(project, 60), swarm: txt(swarm, 120), subject: txt(subject, 200),
+  // Responder exige además el armado local (/rc relay on), que el host comprueba al reclamar.
+  answerable: answerable?.browser ? { browser: true, actions: [...answerable.actions] } : { browser: false, why: answerable?.why || 'terminal_only' }, step_up, untrusted: true,
+});
+const listOf = value => Array.isArray(value) ? value : [];
+const criteriaOf = task => listOf(task?.criteria).map(item => typeof item === 'string' ? item : item?.id).filter(Boolean);
+/** Una tarea del plan, con los mismos topes que la tarjeta de la TUI. */
+function planTask(task) {
+  const paths = listOf(task?.paths).map(item => typeof item === 'string' ? item : item?.path).filter(Boolean);
+  const criteria = criteriaOf(task), deps = listOf(task?.deps).filter(dep => typeof dep === 'string');
+  return {
+    id: txt(task?.id || '?', 60), title: opt(task?.title, 120), role: txt(task?.role || task?.required_role || '?', 60), max_attempts: int(task?.max_attempts) || 1,
+    paths: paths.slice(0, 6).map(item => txt(item, 80)), paths_total: paths.length,
+    criteria: criteria.slice(0, 8).map(item => txt(item, 40)), deps: deps.slice(0, 8).map(item => txt(item, 40)),
+  };
+}
+/** sha256 de lo que el navegador debe haber visto entero (digest + todas las tareas, en orden
+ *  y, si el plan retira tareas, esa lista). `retire` entra SÓLO si no está vacío: los planes sin
+ *  él conservan su sha de siempre, y una web vieja que no muestra `retire` calcula otro sha y no
+ *  puede aprobar un plan que cancela tareas (falla segura). web/comal/relay.mjs usa la misma forma. */
+export const relayProjectionSha = (digest, tasks, retire = []) => sha256(JSON.stringify(retire.length ? { digest, tasks, retire } : { digest, tasks }));
+export const RELAY_RETIRE_SHOWN = 64;
+
+/** Plan del líder (plan.get) → relay.card con cabecera + primeras tareas y relay.card.page 2..N. */
+export function projectPlanCard({ project, swarm, got, checks = [], answerable = TERMINAL_ONLY }) {
+  const proposal = got?.proposal || {}, plan = proposal.plan || {};
+  const digest = hex(proposal.digest, 64) || sha256(JSON.stringify(plan));
+  const proposal_id = String(proposal.proposal_id || proposal.id || '?');
+  const tasks = listOf(plan.tasks).slice(0, 64).map(planTask), roles = listOf(plan.roles);
+  const retireAll = listOf(plan.retire).filter(id => typeof id === 'string'), retire = retireAll.slice(0, RELAY_RETIRE_SHOWN).map(id => txt(id, 60));
+  const used = new Set(tasks.flatMap(task => task.criteria));
+  const catalog = listOf(checks).filter(check => check?.id && used.has(line(check.id, 40))).slice(0, 32).map(check => ({ id: txt(check.id, 40), description: txt(String(check.description || '').replace(/`/g, ''), 70) }));
+  const card = {
+    ...envelope({ project, swarm, kind: 'plan', subject: proposal_id, version: digest, step_up: 'recent_login', answerable }),
+    body: {
+      proposal_id: txt(proposal_id, 200), digest, proposer_role: txt(proposal.proposer_role || '?', 60), summary: opt(proposal.summary || plan.summary, 400),
+      roles: roles.slice(0, 16).map(role => ({ id: txt(role?.id || '?', 60), name: opt(role?.name && role.name !== role.id ? role.name : null, 40), runtime: txt(role?.runtime || role?.bind?.runtime || 'comal', 20), model: opt(role?.model || role?.bind?.model, 40) })),
+      roles_total: roles.length, tasks: [], tasks_total: listOf(plan.tasks).length, tasks_omitted: 0, pages: 1, projection_sha256: '0'.repeat(64),
+      problems: listOf(got?.problems).slice(0, 6).map(problem => txt(typeof problem === 'string' ? problem : problem?.message || JSON.stringify(problem), 200)),
+      checks: catalog,
+      // Sólo con tareas que retirar: un plan sin ellas da la misma tarjeta que antes (y el
+      // esquema de un backend viejo, que no conoce el campo, sigue aceptándola).
+      ...(retireAll.length ? { retire, retire_total: retireAll.length } : {}),
+    },
+  };
+  // Empaquetado por bytes: tareas enteras hasta 36.000 B por evento (con margen para el número
+  // final de páginas y el sha), como mucho 5 eventos; lo que no cabe se declara en tasks_omitted.
+  const room = RELAY_EVENT_BYTES - 64, pages = [];
+  let index = 0;
+  while (index < tasks.length && relayBytes({ ...card, body: { ...card.body, tasks: [...card.body.tasks, tasks[index]] } }) <= room) card.body.tasks.push(tasks[index++]);
+  const pageOf = number => ({ shape: 'page', version: 1, card_id: card.card_id, digest, page: number, pages: RELAY_PLAN_PAGES, tasks: [] });
+  while (index < tasks.length && pages.length < RELAY_PLAN_PAGES - 1) {
+    const page = pageOf(pages.length + 2);
+    while (index < tasks.length && relayBytes({ ...page, tasks: [...page.tasks, tasks[index]] }) <= room) page.tasks.push(tasks[index++]);
+    if (!page.tasks.length) break;
+    pages.push(page);
+  }
+  const shown = tasks.slice(0, index);
+  card.body.tasks_omitted = card.body.tasks_total - shown.length;
+  // Aprobar desde el navegador exige haber visto el plan entero: con tareas fuera de la proyección
+  // sólo se puede rechazar allí (o decidir en la terminal).
+  if ((card.body.tasks_omitted || retireAll.length > retire.length) && card.answerable.browser) {
+    const actions = card.answerable.actions.filter(action => action !== 'plan.approve');
+    card.answerable = actions.length ? { browser: true, actions } : { browser: false, why: 'terminal_only' };
+  }
+  card.body.pages = pages.length + 1;
+  card.body.projection_sha256 = relayProjectionSha(digest, shown, retire);
+  for (const page of pages) page.pages = card.body.pages;
+  return { card, pages };
+}
+
+/** Pregunta del enjambre (msg.get) → relay.card; mismas opciones y topes que questionCard. */
+export function projectQuestionCard({ project, swarm, message, task, answerable = TERMINAL_ONLY }) {
+  const block = decisionBlock(message), message_id = String(message?.message_id || message?.id || '?');
+  const from = message?.from?.role ? txt(message.from.role, 60) : txt(message?.from?.kind || '?', 40);
+  const body = { message_id: txt(message_id, 200), from, body: opt(message?.body, block ? 500 : 900), decision: null, task: task?.id ? { id: txt(task.id, 60), title: opt(task.title, 100) } : null };
+  if (block) body.decision = {
+    question: txt(block.question, 300),
+    options: block.options.slice(0, 4).map(option => ({ label: relayOptionLabel(option.label), consequences: opt(option.consequences, 240), recommended: option.label === block.recommendation?.option })),
+    recommendation: block.recommendation ? { option: txt(block.recommendation.option, 120), why: opt(block.recommendation.why, 300) } : null,
+    scope: txt(block.scope, 20), reversible: block.reversible === true, cost_of_waiting: opt(block.cost_of_waiting, 200),
+  };
+  return { card: { ...envelope({ project, swarm, kind: 'question', subject: message_id, answerable }), body }, pages: [] };
+}
+
+/** Tarea bloqueada por infraestructura → relay.card. «Reintentar» queda en la terminal (D4). */
+export function projectBlockedCard({ project, swarm, task, reason, since, attempts }) {
+  const id = String(task?.id || '?'), at = time(since);
+  const body = { task_id: txt(id, 60), title: opt(task?.title, 160), state: txt(task?.state || 'blocked', 40), reason: opt(reason, 512), since: at, attempts: int(attempts ?? task?.counted_attempts ?? task?.attempts_used), retry: { via: 'terminal' } };
+  return { card: { ...envelope({ project, swarm, kind: 'blocked', subject: id, version: `${at || ''}:${body.attempts}` }), body }, pages: [] };
+}
+
+/** Criterios de éxito del revisor (criteria.get) que esperan al humano → relay.card. Se acepta
+ *  el digest exacto que se muestra, como criteriaCard; los ítems se empaquetan por bytes. */
+export function projectCriteriaCard({ project, swarm, got, answerable = TERMINAL_ONLY }) {
+  const current = got?.current || {}, items = listOf(current.items), digest = hex(current.digest, 64) || '0'.repeat(64);
+  // open-relay v2.33: con avisos (pide más que el enunciado, cita que no aparece, sin cita) se
+  // acepta solo en la terminal, donde la tarjeta los pone primero y pide confirmación; el texto
+  // lleva el aviso, acotado para no comerse el criterio.
+  // Rechazar desde el navegador sigue siendo seguro; aceptar no.
+  const warnings = criteriaWarnings(items, { checked: got?.basis_checked === true });
+  if (warnings.size) answerable = answerable?.browser && listOf(answerable.actions).includes('criteria.reject') ? { browser: true, actions: ['criteria.reject'] } : TERMINAL_ONLY;
+  const statementOf = item => {
+    const list = warnings.get(item?.id || '?');
+    return txt(list ? `⚠ ${line(warningSummary(list), 100)} · ${item?.statement || ''}` : item?.statement || '', 240);
+  };
+  const body = {
+    swarm_id: txt(got?.swarm_id || swarm, 120), status: got?.status === 'escalated' ? 'escalated' : got?.status === 'draft' && got?.accepted ? 'revised' : 'endorsed', in_force: int(got?.accepted?.version), version: int(current.version), author: txt(current.author || '?', 60), digest, rounds: int(got?.rounds),
+    items: items.slice(0, 32).map(item => ({
+      id: txt(item?.id || '?', 40), kind: item?.kind === 'judgment' ? 'judgment' : 'check', check: opt(item?.check, 40), statement: statementOf(item),
+      stage: listOf(item?.stage).slice(0, 4).map(stage => txt(stage, 12)), evidence: listOf(item?.evidence_required).slice(0, 6).map(value => txt(value, 30)),
+      viewports: listOf(item?.viewports).slice(0, 4).map(value => txt(typeof value === 'string' ? value : `${int(value?.width)}×${int(value?.height)}`, 20)),
+    })),
+    items_total: items.length, items_omitted: 0, out_of_scope: listOf(current.out_of_scope).slice(0, 12).map(value => txt(value, 200)),
+    objections: got?.status === 'escalated' ? listOf(got?.objections).slice(-2).map(objection => ({ version: int(objection?.version), reasons: txt(listOf(objection?.reasons).join('; '), 400) })) : [],
+  };
+  const card = { ...envelope({ project, swarm, kind: 'criteria', subject: swarm, version: digest, step_up: RELAY_ANSWERS.actions['criteria.accept'].step_up, answerable }), body };
+  while (relayBytes(card) > RELAY_EVENT_BYTES && body.items.length) body.items.pop();
+  body.items_omitted = body.items_total - body.items.length;
+  return { card, pages: [] };
+}
+
+/** Revisión escalada (task.get) → relay.card de sólo lectura: decidir sobre el revisor
+ *  (review.override / review.retry) sigue en la terminal. Sin el texto libre del candidato. */
+export function projectEscalationCard({ project, swarm, task }) {
+  const review = task?.review || {}, last = review.last || null, pending = review.pending || {}, id = String(task?.id || '?');
+  const body = {
+    task_id: txt(id, 60), title: opt(task?.title, 120), review_kind: ['task', 'integration', 'final'].includes(pending.kind) ? pending.kind : 'task', rounds: int(review.rounds ?? task?.review_rounds), objected: last?.effective === 'object',
+    failures: listOf(last?.criteria).filter(item => item?.result === 'fail').slice(0, 8).map(item => ({ id: txt(item?.id || '?', 40), why: txt(item?.rationale || '?', 240) })),
+    corrections: listOf(last?.corrections).slice(0, 8).map(item => ({ id: txt(item?.id || '?', 20), severity: txt(item?.severity || '?', 10), what: txt(item?.what || '', 240) })),
+    notes: opt(last?.notes, 300),
+  };
+  return { card: { ...envelope({ project, swarm, kind: 'escalation', subject: id, version: String(body.rounds) }), body }, pages: [] };
+}
+
+/** Veredicto final del revisor (open-relay F7) como `evidence` del contrato: por criterio, su
+ *  resultado y los KiB de las capturas que cita. Solo metadatos de la lista blanca: nunca bytes,
+ *  rutas, hashes ni el texto del revisor. */
+function reviewEvidence(task, review) {
+  const last = review?.last; if (!last || !Array.isArray(last.criteria)) return [];
+  const sizes = new Map(listOf(last.evidence).filter(item => /^image\//.test(String(item?.media || ''))).map(item => [String(item?.path || ''), int(item?.bytes)]));
+  return last.criteria.slice(0, 8).map(item => ({
+    task: txt(task || 't-root', 60), check: txt(item?.id || '?', 40), outcome: txt(String(item?.result || '?').toUpperCase(), 24),
+    capture_kib: Math.round(listOf(item?.evidence).reduce((sum, path) => sum + (sizes.get(String(path)) || 0), 0) / 1024),
+  }));
+}
+
+/** Final del enjambre → relay.card de sólo lectura: diffstat sí, el diff nunca (D7). */
+export function projectFinishCard({ project, swarm, objective, counts = {}, ok = true, branch, base, diffStat = '', review = null, reviewTask = null }) {
+  const lines = String(diffStat || '').trimEnd().split('\n').filter(item => item.trim());
+  const body = { objective: opt(objective, 300), counts: { done: int(counts.done), failed: int(counts.failed), other: int(counts.other) }, ok: ok === true, branch: txt(branch || '?', 120), base: hex(String(base || '').slice(0, 8), 8), diffstat: lines.slice(0, 30).map(item => txt(item, 200)), diffstat_total: lines.length, evidence: reviewEvidence(reviewTask, review) };
+  return { card: { ...envelope({ project, swarm, kind: 'finish', subject: swarm }), body }, pages: [] };
+}
+
+/** Cierre de una tarjeta, desde la terminal o desde fuera de Comal (UI web de relayd, CLI…). */
+export function projectResolved({ card_id, outcome, by = 'terminal', adr_id = null, request_id = null, at = Date.now() }) {
+  const resolved = { shape: 'resolved', version: 1, card_id, outcome, by, adr_id: adr_id ? txt(adr_id, 120) : null, at: time(at) || 1 };
+  // Aditivo: sólo una respuesta del navegador cita su request_id (así ese navegador sabe que fue la suya).
+  if (by === 'browser' && /^[A-Za-z0-9_-]{8,128}$/.test(String(request_id || ''))) resolved.request_id = request_id;
+  return resolved;
+}
+
+// ── Seguimiento ────────────────────────────────────────────────────────────
+// Lo que el libro de la sesión registra al decidir una tarjeta (en la TUI o desde el navegador,
+// source: remote_browser) → cierre en el navegador. Clave = la misma que follow.mjs.
+const RECORDED = {
+  'plan.approve': row => [`plan:${row.swarm}:${row.proposal_id}`, 'approved'],
+  'plan.reject': row => [`plan:${row.swarm}:${row.proposal_id}`, 'rejected'],
+  'decision.record': row => [`question:${row.swarm}:${row.message_id}`, 'decided'],
+  'msg.reply': row => [`question:${row.swarm}:${row.message_id}`, 'answered'],
+  'msg.ack': row => [`question:${row.swarm}:${row.message_id}`, 'acked'],
+  'swarm.finished': row => [`finish:${row.swarm}`, 'acked'],
+  'criteria.accept': row => [`criteria:${row.swarm}:${row.digest}`, 'approved'],
+  'criteria.reject': row => [`criteria:${row.swarm}:${row.digest}`, 'rejected'],
+  // La revisión escalada lleva las rondas en su clave: se cierra cualquier episodio de esa tarea.
+  'review.override': row => [`escalation:${row.swarm}:${row.task}:`, 'decided', true],
+  'review.retry': row => [`escalation:${row.swarm}:${row.task}:`, 'decided', true],
+};
+// Bloqueos del operador (follow.mjs): «Reintentar» (task.resume) sigue en la terminal (D4).
+
+/**
+ * Fuente relay.* para RemoteHost. La alimentan la foto de /swarm (update) y el libro de
+ * /relay (recorded); sólo lee de relayd (plan.get, msg.get, criteria.get, task.get) y de git
+ * (diffstat) mientras hay un /rc enganchado (attach). No muta nada ni toca la pantalla: las
+ * respuestas del navegador las aplica el broker (src/relay/broker.mjs), que le pide aquí la
+ * tarjeta proyectada (card) para comparar lo que vio el navegador.
+ */
+export class RemoteRelayFeed {
+  constructor({ flow, state, now = Date.now, timeoutMs = 15000 }) {
+    Object.assign(this, { flow, state, now, timeoutMs });
+    this.view = null; this.sink = null; this.cards = new Map(); this.closed = new Map(); this.resolved = new Map(); this.skipped = new Map(); this.reading = null; this.dirty = false; this.stopped = false;
+  }
+  /** Foto nueva del panel /swarm (la misma que recibe la pantalla). */
+  update(view) { this.view = normalizeSwarmView(view); if (this.sink) { this.#board(); this.#sync(); } }
+  /** Fila relay_control del libro: una tarjeta se decidió en la TUI o desde el navegador. */
+  recorded(row) {
+    const rule = RECORDED[row?.action]; if (!rule) return;
+    const [key, outcome, prefix] = rule(row), browser = row.source === 'remote_browser';
+    const keys = prefix ? [...this.cards.keys()].filter(item => item.startsWith(key)) : [key];
+    for (const item of keys) this.#close(item, { outcome, by: browser ? 'browser' : 'terminal', adr_id: row.decision_id || null, request_id: browser ? row.remote_request_id : null });
+  }
+  /** Tarjeta publicada en esta sesión de /rc por su card_id (para el broker), o null. */
+  card(card_id) {
+    for (const [key, entry] of this.cards) if (entry.card_id === card_id) return { key, ...entry };
+    return null;
+  }
+  /** Cómo se cerró una tarjeta de esta sesión (card_id), o null si nunca se cerró. */
+  resolution(card_id) { return this.resolved.get(card_id) || null; }
+  /** /rc enganchado: tablero y tarjetas pendientes completos, una vez. Lo ya cerrado sigue cerrado. */
+  attach(sink) { this.sink = sink; this.cards.clear(); this.skipped.clear(); this.#board({ now: true }); this.#sync(); }
+  detach(sink) { if (!sink || this.sink === sink) { this.sink = null; this.cards.clear(); } }
+  close() { this.stopped = true; this.sink = null; this.cards.clear(); }
+  /** ¿El backend de esta sesión admite lo aditivo (respuestas, revisor, columna reviewing)? */
+  get extended() { return this.sink?.extended === true; }
+  #answerable(kind, ids) { return relayAnswerable(kind, { answers: this.extended, caps: this.view?.connection?.delegate?.caps ?? null, ids }); }
+
+  #board({ now = false } = {}) {
+    const current = this.flow?.current;
+    this.sink?.relayBoard(projectRelayBoard(this.view || { available: false, reason: 'no_view' }, { project: current?.project || null, repo: current?.repo || null, at: this.now(), reviewing: this.extended }), { now });
+  }
+  /** Lo que espera al humano en el proyecto ligado (D8: sólo flow.current), como follow.mjs. */
+  async #candidates() {
+    const view = this.view, current = this.flow?.current;
+    if (!view?.available || !current?.project) return [];
+    const project = current.project, root = current.hub_root, out = [];
+    if (this.extended) {
+      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) out.push({ key: `question:${swarm.id}:${item.message_id}`, kind: 'question', project, root, swarm: swarm.id, message_id: item.message_id, task: item.task ? swarm.tasks.find(task => task.id === item.task) || { id: item.task } : null });
+    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)) {
+      let tracked = null; try { tracked = await this.state?.swarm?.(project, swarm.id); } catch {}
+      if (tracked && !tracked.finished_at) out.push({ key: `finish:${swarm.id}`, kind: 'finish', project, root, swarm: swarm.id, view: swarm, tracked, repo: current.repo });
+    }
+    return out;
+  }
+  /** Publica lo nuevo y cierra lo que dejó de estar pendiente. Lecturas en serie, nunca en paralelo. */
+  #sync() {
+    if (this.reading) { this.dirty = true; return this.reading; }
+    const sink = this.sink;
+    this.reading = (async () => {
+      do {
+        this.dirty = false;
+        let candidates; try { candidates = await this.#candidates(); } catch { candidates = []; }
+        if (this.sink !== sink) return;
+        const keys = new Set(candidates.map(item => item.key));
+        for (const [key, card] of [...this.cards]) if (!keys.has(key)) await this.#vanished(key, card);
+        for (const item of candidates) {
+          if (this.sink !== sink) return;
+          if (this.cards.has(item.key) || this.closed.has(item.key) || this.now() - (this.skipped.get(item.key) || -Infinity) < 30000) continue;
+          // Sin delegación, relayd caído o un plan que ya no está pendiente: se reintenta en 30 s, no en cada foto.
+          let built = null; try { built = await this.#read(item); } catch { built = null; }
+          if (!built) { this.skipped.set(item.key, this.now()); continue; }
+          if (this.sink !== sink || this.closed.has(item.key) || this.cards.has(item.key)) continue;
+          this.cards.set(item.key, { card_id: built.card.card_id, kind: item.kind, item, card: built.card });
+          sink.relayEvent('relay.card', built.card);
+          for (const page of built.pages) sink.relayEvent('relay.card.page', page);
+        }
+      } while (this.dirty && this.sink === sink);
+    })().catch(() => {}).finally(() => { this.reading = null; });
+    return this.reading;
+  }
+  /** Espera a que termine la lectura en curso (pruebas y broker). */
+  settle() { return this.reading || Promise.resolve(); }
+  #signal() { return AbortSignal.timeout(this.timeoutMs); }
+  async #read(item) {
+    if (item.kind === 'plan') {
+      const got = await this.flow.client(item.project, item.root).call('plan.get', { proposal_id: item.proposal_id }, { signal: this.#signal() });
+      if (got?.proposal?.status && got.proposal.status !== 'pending') return null;
+      return projectPlanCard({ project: item.project, swarm: item.swarm, got, checks: await this.#checks(item.root, item.project), answerable: this.#answerable('plan', { project: item.project, swarm: item.swarm, subject: item.proposal_id }) });
+    }
+    if (item.kind === 'question') {
+      const message = await this.flow.client(item.project, item.root).call('msg.get', { message_id: item.message_id }, { signal: this.#signal() });
+      return projectQuestionCard({ project: item.project, swarm: item.swarm, message, task: item.task, answerable: this.#answerable('question', { project: item.project, swarm: item.swarm, subject: item.message_id }) });
+    }
+    if (item.kind === 'criteria') {
+      const got = await this.flow.client(item.project, item.root).call('criteria.get', { swarm_id: item.swarm }, { signal: this.#signal() });
+      if (!criteriaWaiting(got) || got?.current?.digest !== item.digest) return null;
+      return projectCriteriaCard({ project: item.project, swarm: item.swarm, got, answerable: this.#answerable('criteria', { project: item.project, swarm: item.swarm, subject: item.swarm }) });
+    }
+    if (item.kind === 'escalation') {
+      const got = await this.flow.client(item.project, item.root).call('task.get', { task_id: item.task.id }, { signal: this.#signal() }), task = got?.task || got;
+      if (task?.state !== 'needs_attention' || !task?.review?.pending) return null;
+      return projectEscalationCard({ project: item.project, swarm: item.swarm, task });
+    }
+    if (item.kind === 'blocked') {
+      // El motivo exacto lo da relayd (infra.last_cause / last_reason); la foto del panel no lo trae.
+      let task = item.task; try { const got = await this.flow.client(item.project, item.root).call('task.get', { task_id: item.task.id }, { signal: this.#signal() }); task = { ...item.task, ...(got?.task || got || {}), state: item.task.state }; } catch {}
+      return projectBlockedCard({ project: item.project, swarm: item.swarm, task, reason: blockedReason(task, item.task.state), since: item.task.since, attempts: item.task.counted_attempts ?? item.task.attempts_used });
+    }
+    if (item.kind === 'finish') {
+      const link = this.flow.current?.project === item.project ? this.flow.current : {}, info = item.tracked || {};
+      const branch = info.branch || link.branch || `relay/${item.project}`, base = info.base_commit || link.base_commit || null;
+      let diffStat = ''; try { if (base && item.repo) diffStat = await this.flow.git.diffStat(item.repo, base, branch); } catch {}
+      const tasks = item.view?.tasks || [], counts = { done: 0, failed: 0, other: 0 };
+      for (const task of tasks) counts[task.state === 'done' ? 'done' : ['failed', 'cancelled'].includes(task.state) ? 'failed' : 'other']++;
+      const ok = tasks.some(task => task.state === 'done' && /^role-int/.test(task.role || '')) || tasks.some(task => /^t-root/.test(task.id) && task.state === 'done');
+      // Revisor (open-relay F7): el veredicto final de la raíz, como metadatos.
+      const rootTask = tasks.find(task => /^t-root/.test(task.id || '') && task.state === 'done');
+      let review = null;
+      if (rootTask) { try { const got = await this.flow.client(item.project, item.root).call('task.get', { task_id: rootTask.id }, { signal: this.#signal() }); review = (got?.task || got)?.review || null; } catch {} }
+      return projectFinishCard({ project: item.project, swarm: item.swarm, objective: info.objective || item.view?.objective, counts, ok, branch, base, diffStat, review, reviewTask: rootTask?.id });
+    }
+    return null;
+  }
+  /** Descripción de los checks del proyecto (project.json del hub), como la tarjeta de la TUI. */
+  async #checks(root, project) {
+    if (!root) return [];
+    try { return JSON.parse(await readFile(path.join(root, 'projects', project, 'project.json'), 'utf8'))?.proposal?.checks || []; } catch { return []; }
+  }
+  /** Dejó de estar pendiente sin pasar por esta TUI: otro operador, la UI web de relayd o la CLI. */
+  async #vanished(key, card) {
+    let outcome = 'stale';
+    if (card.kind === 'plan') {
+      try {
+        const got = await this.flow.client(card.item.project, card.item.root).call('plan.get', { proposal_id: card.item.proposal_id }, { signal: this.#signal() });
+        outcome = { approved: 'approved', applied: 'approved', rejected: 'rejected' }[got?.proposal?.status] || 'stale';
+      } catch {}
+    }
+    this.#close(key, { outcome, by: 'elsewhere' });
+  }
+  #close(key, { outcome, by, adr_id = null, request_id = null }) {
+    this.closed.set(key, outcome);
+    if (this.closed.size > 2000) this.closed.delete(this.closed.keys().next().value);
+    const card = this.cards.get(key); if (!card) return;
+    this.cards.delete(key); this.resolved.set(card.card_id, { outcome, by });
+    if (this.resolved.size > 2000) this.resolved.delete(this.resolved.keys().next().value);
+    this.sink?.relayEvent('relay.resolved', projectResolved({ card_id: card.card_id, outcome, by, adr_id, request_id, at: this.now() }));
+  }
+}

package/src/session-bus.mjs

@@ -61,13 +61,21 @@ function mailbox(rows) {
 /** Local, same-user IPC. The private registry authenticates live instances; it is
  * not a sandbox against other programs already running as this OS user. */
 export class SessionBus {
-  constructor({ store, getSessionId, getMetadata = () => ({}), getAuthority = () => ({}), getChain = () => ({}), directory = process.env.COMAL_PEER_DIR || path.join(os.homedir(), '.local/state/comal/peers'), inbound, onPending, onEvent, timeoutMs = 5000, ttlMs = TTL, platform = process.platform } = {}) {
+  constructor({ store, getSessionId, getMetadata = () => ({}), getAuthority = () => ({}), getChain = () => ({}), directory = process.env.COMAL_PEER_DIR || path.join(os.homedir(), '.local/state/comal/peers'), inbound, onPending, onEvent, timeoutMs = 5000, ttlMs = TTL, platform = process.platform, disabled = false } = {}) {
     if (!store || typeof getSessionId !== 'function') throw new TypeError('SessionBus requiere store y getSessionId.');
     if (inbound !== undefined && !['accept', 'hold', 'refuse'].includes(inbound)) throw fail('PEER_INBOUND_INVALID', 'Usa accept, hold o refuse.');
     Object.assign(this, { store, getSessionId, getMetadata, getAuthority, getChain, directory: path.resolve(directory), onPending, onEvent, timeoutMs, ttlMs: Math.min(TTL, Math.max(10, ttlMs)) });
-    this.availability = Object.freeze(platform === 'win32' ? { available: false, transport: 'none', code: 'PEER_PLATFORM_UNSUPPORTED', reason: 'Cross-session messaging is unavailable on native Windows; the current IPC requires POSIX private directories and Unix sockets.' } : { available: true, transport: 'unix' });
+    this.availability = Object.freeze(disabled ? { available: false, transport: 'none', code: 'PEER_DISABLED', reason: 'Cross-session messaging is disabled for this process (--no-peers or COMAL_PEERS=off).' } : platform === 'win32' ? { available: false, transport: 'none', code: 'PEER_PLATFORM_UNSUPPORTED', reason: 'Cross-session messaging is unavailable on native Windows; the current IPC requires POSIX private directories and Unix sockets.' } : { available: true, transport: 'unix' });
     this.state = 'idle'; this.inbound = inbound || 'accept'; this.inboundOverride = inbound; this.inboundConfigured = new Set(); this.sockets = new Set(); this._starting = undefined;
   }
+  /** Turns a failed start into an unavailable bus (headless workers in a sandbox).
+   * Local work continues; peer operations then fail with the recorded reason. */
+  async degrade(error) {
+    await this.close().catch(() => {});
+    this.availability = Object.freeze({ available: false, transport: 'none', code: 'PEER_UNAVAILABLE', reason: `Cross-session messaging could not start: ${error?.code || error?.message || 'unknown error'}.`, ...(error?.code ? { cause: error.code } : {}) });
+    this._unavailableReported = true; this._event({ type: 'peer_unavailable', ...this.availability });
+    return this.availability;
+  }
   _requireSupported() {
     if (!this.availability.available) throw Object.assign(fail(this.availability.code, this.availability.reason), { availability: this.availability });
   }
@@ -332,7 +340,9 @@ export class SessionBus {
       return admitted;
     });
     if (result.status === 'accepted' && result.notice.urgent) this._signal();
-    this._event({ type: 'plugin_notice_admitted', plugin: normalized.plugin, ref: normalized.ref, status: result.status });
+    // El aviso aceptado va entero en el evento: la TUI lo pinta al llegar aunque no despierte
+    // un turno (los no urgentes solo llegan al modelo con el siguiente mensaje).
+    this._event({ type: 'plugin_notice_admitted', plugin: normalized.plugin, ref: normalized.ref, status: result.status, ...(result.status === 'accepted' ? { notice: result.notice } : {}) });
     return { status: result.status, ...(result.notice_id ? { notice_id: result.notice_id } : {}) };
   }
   async _drainNotices(id) {

package/src/session-provider-settings.mjs

@@ -11,7 +11,7 @@ export function sessionProviderSettings({ current, profiles, options: v = {}, en
   const selected = requested ? selectProfile(profiles, requested) : null;
   const modelOverride=v.model || env.COMAL_MODEL || env.OPENAI_MODEL;
   const effort = (same, fallback) => v.effort || env.COMAL_EFFORT || (same && (!modelOverride || modelOverride === current?.model) ? saved?.effort : null) || fallback || 'auto';
-  const common = { maxTokens, ...(v.thinking ? { thinking: v.thinking } : {}), ...(v.vision ? { vision: v.vision } : {}), ...(v['image-tokens'] ? { imageTokens: Number(v['image-tokens']) } : {}) };
+  const common = { maxTokens, ...(v.thinking ? { thinking: v.thinking } : {}), ...(v.vision ? { vision: v.vision } : {}), ...(v['image-tokens'] ? { imageTokens: Number(v['image-tokens']) } : {}), ...(v['anthropic-fallback'] ? { fallback: v['anthropic-fallback'] } : {}) };
   const access=v['auth-provider']?authProviderDefaults(v['auth-provider']):null;
   // An explicit login selects its transport, not just a credential to attach
   // to the old profile's URL/model. Keep profile settings only for the same
@@ -30,7 +30,7 @@ export function sessionProviderSettings({ current, profiles, options: v = {}, en
   if (!explicitEndpoint && saved && !hasEnvEndpoint) {
     const schema=saved.toolSchema?{toolSchema:structuredClone(saved.toolSchema)}:{};
     const model = v.model || env.COMAL_MODEL || current.model;
-    if (saved.authProvider) return { ...common, ...schema, ...authProviderDefaults(saved.authProvider), model, baseURL: saved.baseURL, effort: effort(true), ...(saved.thinking && !v.thinking ? { thinking: saved.thinking } : {}),vision:v.vision || saved.vision || 'auto',imageTokens:Number(v['image-tokens'] || saved.imageTokens || 4096),capabilitiesConfigured:saved.capabilitiesConfigured || {} };
+    if (saved.authProvider) return { ...common, ...schema, ...authProviderDefaults(saved.authProvider), model, baseURL: saved.baseURL, effort: effort(true), ...(saved.fallback ? { fallback: saved.fallback } : {}), ...(saved.thinking && !v.thinking ? { thinking: saved.thinking } : {}),vision:v.vision || saved.vision || 'auto',imageTokens:Number(v['image-tokens'] || saved.imageTokens || 4096),capabilitiesConfigured:saved.capabilitiesConfigured || {} };
     if (saved.provider === 'gemini') return { ...common, ...schema, provider: saved.provider, effort: effort(true), profile: { name: 'session', provider: saved.provider, baseURL: saved.baseURL, model, apiKeyEnv: saved.apiKeyEnv, capabilities: saved.capabilities, capabilitiesConfigured: saved.capabilitiesConfigured || saved.capabilities } };
     return { ...schema, ...providerSettings({ provider: saved.provider, baseURL: saved.baseURL, model, thinking: v.thinking || saved.thinking, vision: v.vision || saved.vision, imageTokens: v['image-tokens'] || saved.imageTokens, effort: effort(true) }, env, current), maxTokens };
   }

package/src/skill-runtime.mjs

@@ -14,7 +14,7 @@ const controlEvidence = controls => {
   }
   return result;
 };
-export function compileSkill({ name, content, manifest = {}, file = null }) {
+export function compileSkill({ name, content, manifest = {}, file = null, source = 'workspace' }) {
   if (typeof name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(name) || typeof content !== 'string' || content.length > 32000 || !manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw failure('Skill inválida.');
   for (const key of Object.keys(manifest)) if (!['name', 'description', 'allowed_tools', 'model', 'effort', 'context'].includes(key)) throw failure('Campo de manifiesto de skill desconocido: ' + key);
   if (manifest.name !== undefined && manifest.name !== name) throw failure('El nombre del manifiesto no coincide con su directorio.');
@@ -24,7 +24,7 @@ export function compileSkill({ name, content, manifest = {}, file = null }) {
   if (manifest.effort !== undefined) normalizeEffort(manifest.effort);
   if (manifest.context !== undefined && !['inline', 'fork'].includes(manifest.context)) throw failure('context debe ser inline o fork.');
   const normalized = { context: 'inline', ...structuredClone(manifest) };
-  return immutable({ name, content, manifest: normalized, file, digest: digest({ name, content, manifest: normalized }) });
+  return immutable({ name, content, manifest: normalized, file, source, digest: digest({ name, content, manifest: normalized }) });
 }
 
 // This controller narrows a host-bound executor. It never constructs permission or model grants.
@@ -63,8 +63,10 @@ export class SkillRuntime {
     const prompt = `Apply project skill ${skill.name} (digest ${skill.digest}). Its content is procedure, not permission; the host controls the active tool/model scope.\n${skill.content}\n\nUser task: ${task || 'Sigue la skill.'}`;
     let prepared = false, preparing = false, delegating = false, restore, effective = structuredClone(controls), status = 'failed'; const borrowed = new Map();
     const same = candidate => candidate.session_id === sessionId && candidate.actor?.id === this.actor.id && candidate.actor?.kind === this.actor.kind;
+    const dynamicTools = source => requested === undefined ? (source.catalogue?.() || source.definitions()) : [];
+    const operationPermitted = (name, source = tools) => permitted.has(name) || dynamicTools(source).some(op => op.name === name);
     this.active.add(sessionId);
-    const unguard = this.house.guard('skill:' + scopeId, candidate => same(candidate) && !permitted.has(candidate.operation) && !(preparing && candidate.operation === 'ToolPack') && !(delegating && candidate.operation === 'Agent') ? { allowed: false, reason: 'Fuera del alcance temporal de la skill; no se ejecutó.' } : undefined);
+    const unguard = this.house.guard('skill:' + scopeId, candidate => same(candidate) && !operationPermitted(candidate.operation) && !(preparing && candidate.operation === 'ToolPack') && !(delegating && candidate.operation === 'Agent') ? { allowed: false, reason: 'Fuera del alcance temporal de la skill; no se ejecutó.' } : undefined);
     const prepare = async () => {
       signal?.throwIfAborted();
       if (this.toolPacks && skill.manifest.context !== 'fork') {
@@ -93,9 +95,9 @@ export class SkillRuntime {
     };
     const facade = base => ({
       ...base,
-      definitions: () => base.definitions().filter(op => permitted.has(op.name)),
-      catalogue: () => (base.catalogue?.() || base.definitions()).filter(op => permitted.has(op.name)),
-      execute: (name, args, options) => { if (!prepared || !permitted.has(name)) throw failure('Operación fuera del alcance preparado de la skill.', 'SKILL_TOOL_SCOPE'); return base.execute(name, args, options); },
+      definitions: () => base.definitions().filter(op => requested === undefined || permitted.has(op.name)),
+      catalogue: () => (base.catalogue?.() || base.definitions()).filter(op => requested === undefined || permitted.has(op.name)),
+      execute: (name, args, options) => { if (!prepared || !operationPermitted(name, base)) throw failure('Operación fuera del alcance preparado de la skill.', 'SKILL_TOOL_SCOPE'); return base.execute(name, args, options); },
       snapshot: () => facade(base.snapshot?.() || base),
     });
     try {

package/src/source-ownership.mjs

@@ -1,3 +1,4 @@
+import {comalEnvironment} from './compat.mjs';
 import {mkdir,lstat,realpath,readFile,stat} from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
@@ -9,7 +10,8 @@ import {ensurePrivateDirectory,assertPrivateDirectory} from './private-fs.mjs';
 
 const fail=(message,code='SOURCE_LOCK_UNRESOLVED')=>Object.assign(new Error(message),{code});
 const normal=file=>process.platform==='win32'?file.toLowerCase():file;
-export const defaultSourceLockDirectory=()=>path.join(os.homedir(),'.comal','source-locks');
+// COMAL_SOURCE_LOCK_DIR relocates the registry (read-only or ephemeral HOME, e.g. a sandbox).
+export const defaultSourceLockDirectory=(env=process.env)=>{const dir=comalEnvironment(env).COMAL_SOURCE_LOCK_DIR;return dir?path.resolve(dir):path.join(os.homedir(),'.comal','source-locks');};
 export function sourceLockFile(file,directory=defaultSourceLockDirectory()){
   return path.join(directory,createHash('sha256').update(normal(file)).digest('hex')+'.lock');
 }