create-panal-agent 0.13.0 → 0.13.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-panal-agent",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Crea un agente de IA para Panal, funcionando y cobrando on-chain, en cinco minutos",
   "type": "module",
   "license": "MIT",
@@ -42,6 +42,6 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx test/i18n.test.ts && tsx test/memoria.test.ts && tsx test/reintento.test.ts && tsx test/zip.test.ts && tsx test/adjuntos.test.ts && tsx test/salida.test.ts && tsx test/scaffold.test.ts"
+    "test": "tsx test/i18n.test.ts && tsx test/memoria.test.ts && tsx test/reintento.test.ts && tsx test/zip.test.ts && tsx test/adjuntos.test.ts && tsx test/salida.test.ts && tsx test/vigilante.test.ts && tsx test/scaffold.test.ts"
   }
 }

package/template/src/agent.ts

@@ -13,7 +13,7 @@
 
 import { llmChat, resolverLlm, type CallEnvelope, type LlmConfig } from '@panal/sdk';
 import { leerAdjuntos, type AdjuntoRecibido, type AdjuntosLeidos } from './adjuntos.js';
-import { comoArchivo, formatoPedido } from './salida.js';
+import { comoArchivo, formatoPedido, nombreDelTema } from './salida.js';
 import { historialComoTexto, type Turno } from './memoria.js';
 
 /**
@@ -199,7 +199,7 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
     const problema = revisar(brief, texto);
     if (!problema) {
       console.log(`[agente] ${etiqueta(ctx)} resuelta: ${texto.length} caracteres`);
-      return conArchivoSiLoPidio(brief, texto, ctx);
+      return await conArchivoSiLoPidio(brief, texto, ctx);
     }
     console.error(`[agente] ${etiqueta(ctx)} intento ${intento}: ${problema}`);
     // A la segunda se entrega igual. Tu revisión puede equivocarse, y un falso
@@ -207,7 +207,7 @@ export async function handleTask(brief: string, ctx: TaskContext): Promise<TaskR
     // entregar algo imperfecto y que él decida, que dejarlo sin nada.
     if (intento === 2) {
       console.error(`[agente] ${etiqueta(ctx)} se entrega pese a: ${problema}`);
-      return conArchivoSiLoPidio(brief, texto, ctx);
+      return await conArchivoSiLoPidio(brief, texto, ctx);
     }
     queja = problema;
   }
@@ -372,10 +372,10 @@ function revisar(brief: string, resultado: string): string | null {
  * lo ancla en la cadena, así que el cliente puede demostrar que el archivo que
  * se baja es exactamente el que le entregaste.
  */
-function conArchivoSiLoPidio(brief: string, texto: string, ctx: TaskContext): TaskResult {
+async function conArchivoSiLoPidio(brief: string, texto: string, ctx: TaskContext): Promise<TaskResult> {
   const formato = formatoPedido(brief);
   if (!formato) return texto;
-  const archivo = comoArchivo(formato, 'entrega', `Panal - entrega ${etiqueta(ctx)}`, texto);
+  const archivo = comoArchivo(formato, await nombreDelTema(brief, 'entrega'), `Panal - entrega ${etiqueta(ctx)}`, texto);
   const bytes = typeof archivo.data === 'string' ? archivo.data.length : archivo.data.byteLength;
   console.log(`[agente] ${etiqueta(ctx)} ${archivo.name} de ${bytes} bytes adjunto`);
   // El TEXTO se sigue entregando: es lo que se ancla en la cadena. El archivo

package/template/src/register.ts

@@ -38,6 +38,27 @@ const PERFIL = {
   // vacía NO la sustituye `??`. Con `??` el botUrl acababa siendo '' y la
   // comprobación de "no has puesto tu URL" no saltaba nunca.
   botUrl: process.env.PUBLIC_URL?.trim() || 'https://cambia-esto.example.com',
+
+  // TU CARA, si quieres tenerla. Todo esto es opcional y va vacío por defecto:
+  // un agente sin logo no vale menos, es lo que hay hoy en todo el mercado.
+  //
+  // Lo que compra ponerlo es que el cliente pueda MIRARTE antes de pagarte. En
+  // el mercado sales entre desconocidos, y un repositorio que se puede abrir
+  // dice más de ti que cualquier descripción que escribas de ti mismo.
+  //
+  // Se guarda en tu ficha del registro, así que cambiarlo cuesta una
+  // transacción: `npm run register` otra vez y ya.
+  links: {
+    // El logo sale en tu tarjeta, en el mercado y en la app. Https, cuadrado y
+    // pequeño: se pinta a 56 px, no hace falta más.
+    logo: '',
+    web: '',
+    // Tu perfil o el repositorio del agente: valen `usuario` y `usuario/repo`.
+    github: '',
+    // Solo el usuario; también se traga el enlace entero si lo pegas.
+    x: '',
+    telegram: '',
+  },
 };
 
 /** Lo que cobras por tarea. */

package/template/src/salida.ts

@@ -15,6 +15,7 @@
  * peso y confusión.
  */
 
+import { llmChat, resolverLlm, stripFilesManifest } from '@panal/sdk';
 import { textoAPdf } from './pdf.js';
 import { escribirZip } from './zip.js';
 
@@ -36,7 +37,20 @@ export interface ArchivoDeSalida {
  * Devuelve `null` cuando no pide nada, que es el caso normal.
  */
 export function formatoPedido(brief: string): Formato | null {
-  const t = brief.toLowerCase();
+  // El manifiesto de adjuntos NO es lo que pidio el cliente: es contabilidad
+  // del protocolo, y va pegada al FINAL del brief. Sin quitarla, sus lineas
+  // `name:` y `mime:` son las ultimas menciones de un formato que hay en el
+  // texto, y esta funcion se queda justamente con la ultima.
+  //
+  // El efecto es que el adjunto elige el formato de SALIDA. Comprobado en un
+  // encargo real de mainnet (#67): el cliente pidio JSON, adjunto un `.txt`, y
+  // el manifiesto —`name: pedidos n.txt`, `mime: text/plain`— gano al «devuelve
+  // solo el JSON» que estaba escrito antes. Se entrego un .txt.
+  //
+  // No es raro ni un caso de laboratorio: casi todo adjunto lleva en el nombre
+  // una extension que aqui es un formato. Adjuntar un PDF hacia que la entrega
+  // fuera un PDF, se pidiera lo que se pidiera.
+  const t = stripFilesManifest(brief).toLowerCase();
   const mencion: { formato: Formato; en: number }[] = [];
 
   for (const [formato, patron] of PATRONES) {
@@ -334,6 +348,159 @@ export function comoTabla(texto: string): string | null {
   ].join('\n');
 }
 
+/* ── cómo se llama el archivo ────────────────────────────────────────────── */
+
+/**
+ * Los reservados de Windows y los separadores de ruta.
+ *
+ * NO se tocan las letras: un nombre en chino, en árabe o con tildes es un
+ * nombre perfectamente válido, y quitárselos sería justo lo contrario de lo
+ * que hace falta aquí.
+ */
+const PROHIBIDOS = /[/\\:*?"<>|]/g;
+
+/** Cuántos caracteres como mucho. Un nombre no es un resumen. */
+const MAX_NOMBRE = 60;
+
+/** ¿Es un carácter imprimible? Los de control no valen en un nombre. */
+function imprimible(c: string): boolean {
+  const p = c.codePointAt(0) ?? 0;
+  return p >= 0x20 && p !== 0x7f;
+}
+
+/**
+ * Un título cualquiera, convertido en nombre de archivo.
+ *
+ * Se exporta para poder probarlo sin gastar una llamada al modelo.
+ */
+export function comoNombre(crudo: string): string {
+  const linea = crudo.split(/\r?\n/).find((l) => l.trim()) ?? '';
+  const limpio = [...linea]
+    .filter(imprimible)
+    .join('')
+    .trim()
+    // El modelo devuelve el título entrecomillado más veces de las que parece.
+    .replace(/^["'`«“]+|["'`»”]+$/g, '')
+    // Y a veces le pone extensión, que aquí la pone `comoArchivo`.
+    .replace(/\.(pdf|docx?|xlsx?|md|txt|csv|json|zip)$/i, '')
+    .replace(PROHIBIDOS, ' ')
+    .replace(/\s+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .toLowerCase();
+  // Por code points y no con `.slice`: cortar por unidades UTF-16 parte por la
+  // mitad un carácter fuera del plano básico.
+  return [...limpio].slice(0, MAX_NOMBRE).join('').replace(/[-.]+$/, '');
+}
+
+/**
+ * La cabecera `content-disposition` de un archivo que se descarga.
+ *
+ * DOS FORMAS DEL NOMBRE, Y LAS DOS HACEN FALTA (RFC 6266). Una cabecera HTTP
+ * solo admite latin-1, y desde que el nombre del archivo lo escribe el modelo
+ * en el idioma del cliente, un entregable puede llamarse
+ * `两个整数相除.pdf`. Interpolarlo tal cual en `filename="…"` no da un nombre
+ * feo: Node LANZA `ERR_INVALID_CHAR` al escribir la cabecera y la descarga
+ * responde 500. El archivo estaba entregado, pagado y anclado en la cadena, y
+ * el cliente no podía bajárselo.
+ *
+ *   filename=   una versión en ASCII, para quien no entienda lo otro
+ *   filename*=  el nombre de verdad, en UTF-8 percent-encoded
+ *
+ * Los navegadores prefieren `filename*` cuando está, así que el nombre bueno
+ * es el que se ve. Y las comillas se van del ASCII a propósito: una comilla
+ * dentro de `filename="…"` parte la cabecera por la mitad.
+ */
+export function comoAdjunto(nombre: string): string {
+  const ascii =
+    [...nombre]
+      .map((c) => {
+        const p = c.codePointAt(0) ?? 0;
+        return p >= 0x20 && p < 0x7f && c !== '"' && c !== '\\' ? c : '_';
+      })
+      .join('')
+      .replace(/_{2,}/g, '_')
+      .replace(/^[_.]+|[_.]+$/g, '') || 'archivo';
+  return `attachment; filename="${ascii}"; filename*=UTF-8''${encodeURIComponent(nombre)}`;
+}
+
+/**
+ * Lo que se le pide al modelo. Corto a propósito: es un nombre, no un resumen.
+ *
+ * Las dos reglas que de verdad cambian el resultado son las dos últimas. Sin
+ * la del SUJETO, el modelo nombra la acción —«escribir-casos-de-prueba»— y
+ * todos los archivos de un mismo agente vuelven a llamarse igual, que es el
+ * problema que esto viene a arreglar. Y sin la del IDIOMA contesta en inglés
+ * aunque el encargo venga en otro, porque el inglés es su idioma por defecto.
+ */
+const PIDE_UN_NOMBRE =
+  'You name files. Given a client request, reply with ONLY a file name for the deliverable.\n' +
+  'Two to five words. No extension, no quotes, no path, no explanation, no punctuation at the ends.\n' +
+  'Name the SUBJECT the work is about, never the action asked for: for "write the test cases for a ' +
+  'function that divides two integers" answer "division de dos enteros", not "escribir casos de prueba".\n' +
+  'Write it in the SAME language the client wrote in, in their own script. Do not translate it to English.';
+
+/**
+ * El nombre del archivo que se entrega, sacado del TEMA del encargo.
+ *
+ * ANTES TODOS SE LLAMABAN IGUAL. Cada agente tenía un nombre fijo —
+ * `casos-de-prueba.pdf`, `revision.pdf`, `traducciones.pdf`—, así que un
+ * cliente que encargara tres cosas al mismo agente acababa con tres archivos
+ * del mismo nombre en su carpeta de descargas, pisándose unos a otros o
+ * quedando como «casos-de-prueba (2).pdf». Y estaba en castellano para todo el
+ * mundo, cuando el contenido va en el idioma del cliente desde hace tiempo.
+ *
+ * EL TEMA SALE DEL ENCARGO, no de la entrega. La entrega es texto plano sin
+ * título —el prompt prohíbe los encabezados a propósito—, así que su primera
+ * línea es el primer caso de prueba, no de qué va la cosa. El encargo, en
+ * cambio, lo escribió el cliente: dice el tema y está en su idioma.
+ *
+ * NUNCA LANZA Y NUNCA DEVUELVE VACÍO. Si el modelo no contesta, tarda o
+ * devuelve algo que no sirve, se usa el nombre de siempre. Nombrar un archivo
+ * no puede impedir entregarlo: el pago ya está bloqueado.
+ */
+export async function nombreDelTema(brief: string, deReserva: string): Promise<string> {
+  try {
+    const cfg = resolverLlm(process.env);
+    const respuesta = await llmChat(
+      // NO SE TOCA NI LA TEMPERATURA NI EL TOPE DE TOKENS, y las dos cosas se
+      // aprendieron probando contra el modelo de verdad.
+      //
+      // Aquí ponía `temperature: 0` —lo natural para pedir algo determinista— y
+      // el modelo lo rechazaba con un 400: hay modelos que solo aceptan 1. Y
+      // ponía `maxTokens: 32` —es un nombre, no un texto— y la respuesta volvía
+      // con `choices` vacío, porque un modelo que razona antes de contestar se
+      // gasta ese presupuesto pensando y no le queda para escribir.
+      //
+      // Los dos fallos son INVISIBLES: se cae al nombre de siempre, que es
+      // exactamente lo que había antes, así que la función habría quedado
+      // muerta sin que nadie lo notara. Se hereda lo que el operador ya tiene
+      // configurado, que es lo que funciona en el resto de sus llamadas.
+      //
+      // Lo único propio es el reloj: un timeout más corto que el del trabajo y
+      // un solo reintento, porque esto va DESPUÉS de tener la entrega hecha y
+      // no puede retrasarla.
+      { ...cfg, timeoutMs: 20_000, maxRetries: 1 },
+      // El encargo entero no hace falta: el tema está al principio, y mandarlo
+      // completo puede ser mandar un contrato de treinta páginas para sacar
+      // cuatro palabras.
+      // Sin el manifiesto, por lo mismo que en `formatoPedido`: son 1.500
+      // caracteres de presupuesto y un hash de 64 ocupa sitio sin decir nada
+      // del tema. Con adjuntos cortos llegaba a colarse entero.
+      { system: PIDE_UN_NOMBRE, user: stripFilesManifest(brief).trim().slice(0, 1_500) },
+    );
+    const nombre = comoNombre(respuesta);
+    if (nombre) return nombre;
+    console.warn(`[salida] el modelo no dio un nombre usable; el archivo va como «${deReserva}»`);
+  } catch (err) {
+    console.warn(
+      `[salida] no se pudo nombrar el archivo (${err instanceof Error ? err.message.split('\n')[0] : err}); ` +
+        `va como «${deReserva}»`,
+    );
+  }
+  return deReserva;
+}
+
 /**
  * El archivo listo para adjuntar a la entrega.
  *

package/template/src/server.ts

@@ -47,6 +47,7 @@ import {
   type DeliveredFile,
   type PermitDomain,
 } from '@panal/sdk';
+import { comoAdjunto } from './salida.js';
 import { privateKeyToAccount } from 'viem/accounts';
 import { isAddress, keccak256, parseEther, toBytes, verifyMessage } from 'viem';
 import type { Address } from 'viem';
@@ -535,9 +536,28 @@ function contexto(
   };
 }
 
-async function work(taskId: bigint, brief: string, sobre: CallEnvelope | null): Promise<void> {
+/**
+ * Cómo acabó un intento de trabajar una tarea.
+ *
+ * Existe porque `work()` no puede lanzar —también lo llama una ruta HTTP, y
+ * una tarea rota no debe tumbar la ronda del vigilante— y sin embargo el
+ * vigilante NECESITA distinguir. Antes no podía: un modelo que devolvía 429
+ * dos veces seguidas y una entrega perfecta se veían igual desde fuera, así
+ * que la tarea se daba por resuelta y se dejaba de mirar. Pasó con la #55.
+ *
+ * `esperando` no es un fallo y tampoco es un éxito, y por eso no bastaba con
+ * relanzar el error: una tarea a la que le faltan adjuntos sale de aquí sin
+ * ningún error y sin haberse entregado.
+ */
+export type ResultadoTrabajo = 'entregada' | 'esperando' | 'fallo' | 'en-curso';
+
+async function work(
+  taskId: bigint,
+  brief: string,
+  sobre: CallEnvelope | null,
+): Promise<ResultadoTrabajo> {
   const key = taskId.toString();
-  if (inFlight.has(key)) return;
+  if (inFlight.has(key)) return 'en-curso';
   inFlight.add(key);
   try {
     // Lo PRIMERO, antes de trabajar: si el proceso muere a mitad, esto es lo
@@ -556,7 +576,10 @@ async function work(taskId: bigint, brief: string, sobre: CallEnvelope | null):
       console.log(
         `[panal] #${taskId} en espera de ${faltan.length} adjunto(s): ${faltan.map((f) => f.name).join(', ')}`,
       );
-      return;
+      // Salida limpia y sin entregar. El vigilante tiene que verlo tal cual:
+      // dándola por resuelta, una tarea cuyo adjunto llega tras un reinicio se
+      // quedaba esperando para siempre sin que nadie volviera a mirarla.
+      return 'esperando';
     }
     if (recibidos.length > 0) console.log(`[panal] #${taskId} con ${recibidos.length} adjunto(s) del cliente`);
 
@@ -590,8 +613,10 @@ async function work(taskId: bigint, brief: string, sobre: CallEnvelope | null):
     saveResult(taskId, text);
     const { txHash } = await panal.deliverResult(taskId, text);
     console.log(`[panal] #${taskId} entregada · tx ${txHash}`);
+    return 'entregada';
   } catch (err) {
     console.error(`[panal] #${taskId} falló: ${err instanceof Error ? err.message : err}`);
+    return 'fallo';
   } finally {
     inFlight.delete(key);
   }
@@ -1395,7 +1420,7 @@ const server = createServer((req, res) => {
         'content-length': bytes.byteLength,
         // `attachment` a propósito: lo que hay dentro lo eligió el agente, y no
         // se le deja que el navegador del cliente lo ejecute como una página.
-        'content-disposition': `attachment; filename="${nombre}"`,
+        'content-disposition': comoAdjunto(nombre),
         'x-content-type-options': 'nosniff',
       });
       res.end(bytes);
@@ -1439,7 +1464,9 @@ arrancarVigilante({
   // que la sostenía murió—, así que esta reanudación no puede seguir gastando
   // en nombre de nadie. Si el encargo necesitaba subcontratar, lo hará con el
   // presupuesto propio de este agente y no con el de quien llamó.
-  trabajar: (taskId, brief) => work(taskId, brief, null),
+  // Solo `entregada` cuenta como resuelta. Un fallo del modelo o una espera de
+  // adjuntos devuelven false y la tarea se queda en la lista del vigilante.
+  trabajar: async (taskId, brief) => (await work(taskId, brief, null)) === 'entregada',
   reentregar: async (taskId, texto) => {
     const { txHash } = await panal.deliverResult(taskId, texto);
     console.log(`[vigilante] #${taskId} entregada al segundo intento · tx ${txHash}`);

package/template/src/vigilante.ts

@@ -21,6 +21,20 @@
  * el enlace de reenvío y se espera. Adivinar sería entregar cualquier cosa
  * anclando su hash, que es peor que no entregar.
  *
+ * «MIRADA» NO ES «RESUELTA», y confundirlas costó dos tareas de verdad.
+ *
+ * La marca guarda hasta dónde se ha ENUMERADO, no hasta dónde se ha resuelto.
+ * Antes se escribía al final de cada ronda pasara lo que pasara, así que una
+ * tarea que fallaba a mitad —el modelo colgado, el RPC caído— se quedaba por
+ * detrás de la marca y no volvía a mirarse nunca. Y lo que la recordaba vivía
+ * solo en memoria, o sea que un reinicio conservaba la mitad optimista (la
+ * marca, en disco) y perdía la otra (los pendientes, en RAM).
+ *
+ * Ahora las dos cosas viven en el MISMO archivo y se escriben juntas: la marca
+ * dice hasta dónde se enumeró, y `pendientes` lleva las excepciones. Una tarea
+ * sale de esa lista cuando de verdad se cierra —entregada, completada,
+ * cancelada— y no cuando se intentó algo con ella.
+ *
  * SE SONDEA, NO SE ESCUCHAN EVENTOS. `eth_getLogs` del RPC público está
  * limitado a 100 bloques, así que un agente parado veinte minutos ya no puede
  * recuperar su propio hueco. Leer el contador de tareas y mirar las nuevas es
@@ -40,8 +54,20 @@ export interface VigilanteDeps {
   yo: Address;
   /** Dónde guardar hasta dónde se miró. */
   dataDir: string;
-  /** Trabaja una tarea de la que YA se tiene el encargo. */
-  trabajar: (taskId: bigint, brief: string) => Promise<void>;
+  /**
+   * Trabaja una tarea de la que YA se tiene el encargo.
+   *
+   * Devuelve si la ENTREGÓ, y ese booleano es media corrección de este archivo.
+   * `work()` está escrito para no lanzar nunca —una tarea rota no puede tumbar
+   * la ronda entera—, así que desde aquí un reintento que funcionó y uno que
+   * volvió a reventar por límite de uso se veían exactamente igual: sin error.
+   * El vigilante daba por buena la tarea y dejaba de mirarla.
+   *
+   * Y no vale con relanzar el error: `work()` también sale limpio cuando la
+   * tarea espera adjuntos que no han llegado, que tampoco es haberla resuelto.
+   * Hace falta que lo diga, no que se deduzca de que nadie protestó.
+   */
+  trabajar: (taskId: bigint, brief: string) => Promise<boolean>;
   /**
    * ¿Se está trabajando esa tarea AHORA MISMO?
    *
@@ -100,98 +126,180 @@ const GRACIA_MS = 3 * 60 * 1000;
 /** Cuántas tareas hacia atrás se miran al arrancar sin marca previa. */
 const REPASO_INICIAL = 50n;
 
+/**
+ * Tope de la lista de pendientes.
+ *
+ * Una tarea sale de la lista cuando se cierra —entregada, completada,
+ * cancelada—, y todas acaban cerrándose: al vencer el plazo el cliente
+ * recupera su dinero y la tarea deja de estar abierta. Aun así el tope existe
+ * porque nadie OBLIGA al cliente a cancelar: una tarea abandonada puede
+ * quedarse abierta para siempre, y sin tope el archivo crecería sin fin.
+ *
+ * Al recortar se tiran las más VIEJAS, que son las que menos se pueden
+ * recuperar, y se dice en voz alta. Callarlo sería repetir el fallo que este
+ * archivo viene a arreglar.
+ */
+const MAX_PENDIENTES = 500;
+
+/** Qué se sabe de una tarea tras mirarla. «Se intentó» no es un veredicto. */
+type Veredicto = 'resuelta' | 'pendiente';
+
 export function arrancarVigilante(deps: VigilanteDeps): { parar: () => void } {
   if (process.env.VIGILANTE === 'off') {
     console.log('Vigilante desactivado (VIGILANTE=off).');
     return { parar: () => {} };
   }
 
-  const marcaPath = join(deps.dataDir, 'vigilante.json');
-  /** Tareas vistas sin encargo, con el momento en que se vieron. */
-  const huerfanas = new Map<string, number>();
+  const estadoPath = join(deps.dataDir, 'vigilante.json');
+  /**
+   * Cuándo se vio por primera vez una tarea sin encargo.
+   *
+   * Esto SÍ puede vivir solo en memoria: solo sirve para el margen de gracia
+   * antes de gritar, y perderlo en un reinicio únicamente reinicia esa cuenta
+   * atrás. Lo que no puede vivir solo en memoria es la lista de pendientes, y
+   * por eso está aparte.
+   */
+  const vistas = new Map<string, number>();
   /** De las que ya se avisó, para no repetir el aviso cada vuelta. */
   const avisadas = new Set<string>();
+  /** De los encargos guardados que no cuadran, para no repetir la queja. */
+  const quejadas = new Set<string>();
   let parado = false;
 
-  const leerMarca = (): bigint => {
+  interface Estado {
+    visto: bigint;
+    pendientes: Set<string>;
+  }
+
+  const leerEstado = (): Estado => {
     try {
-      const raw = JSON.parse(readFileSync(marcaPath, 'utf8')) as { visto?: string };
-      return BigInt(raw.visto ?? '0');
+      const raw = JSON.parse(readFileSync(estadoPath, 'utf8')) as {
+        visto?: string;
+        pendientes?: string[];
+      };
+      return {
+        // -1 y no 0: sin marca hay que hacer el repaso inicial.
+        visto: raw.visto === undefined ? -1n : BigInt(raw.visto),
+        // Un archivo de la versión anterior no trae la lista. Se lee como
+        // vacía y la primera ronda la vuelve a poblar con lo que siga abierto
+        // por delante de la marca; lo que quedó huérfano por detrás hay que
+        // recuperarlo a mano, que es exactamente el destrozo que esto corrige.
+        pendientes: new Set(raw.pendientes ?? []),
+      };
     } catch {
-      return -1n; // sin marca: se hace el repaso inicial
+      return { visto: -1n, pendientes: new Set() };
     }
   };
-  const escribirMarca = (visto: bigint): void => {
+
+  /**
+   * Las dos cosas se escriben JUNTAS, y ahí está la corrección.
+   *
+   * Antes la marca iba a disco y los pendientes se quedaban en RAM, así que un
+   * reinicio guardaba la mitad que dice «ya miré» y perdía la que dice «pero
+   * esto sigue sin resolver». En un solo archivo no puede pasar.
+   */
+  const escribirEstado = (visto: bigint, pendientes: Set<string>): void => {
+    let lista = [...pendientes];
+    if (lista.length > MAX_PENDIENTES) {
+      // Ordenadas por id: las más viejas primero, que son las que se tiran.
+      lista.sort((a, b) => (BigInt(a) < BigInt(b) ? -1 : 1));
+      const tiradas = lista.slice(0, lista.length - MAX_PENDIENTES);
+      lista = lista.slice(-MAX_PENDIENTES);
+      console.error(
+        `[vigilante] la lista de pendientes pasó de ${MAX_PENDIENTES}: dejo de seguir ` +
+          `${tiradas.length} tarea(s) vieja(s) (#${tiradas[0]}…#${tiradas[tiradas.length - 1]}). ` +
+          'Míralas a mano si alguna sigue abierta.',
+      );
+    }
     try {
-      writeFileSync(marcaPath, JSON.stringify({ visto: visto.toString() }, null, 2));
+      writeFileSync(estadoPath, JSON.stringify({ visto: visto.toString(), pendientes: lista }, null, 2));
     } catch (err) {
-      // Perder la marca solo cuesta repetir el repaso, así que no se para nada.
-      console.error(`[vigilante] no se pudo guardar la marca: ${err instanceof Error ? err.message : err}`);
+      // Perder el estado cuesta repetir el repaso, así que no se para nada.
+      console.error(`[vigilante] no se pudo guardar el estado: ${err instanceof Error ? err.message : err}`);
     }
   };
 
   /** true si encontro algo que atender: eso es lo que decide el ritmo. */
   async function repasar(): Promise<boolean> {
     const total = await deps.panal.getTaskCount();
-    const marca = leerMarca();
+    const { visto, pendientes } = leerEstado();
     // La primera vez se miran las últimas REPASO_INICIAL en vez de las 30.000
     // que pueda haber: las viejas están cerradas y no cambian.
-    const desde = marca >= 0n ? marca + 1n : total > REPASO_INICIAL ? total - REPASO_INICIAL : 0n;
+    const desde = visto >= 0n ? visto + 1n : total > REPASO_INICIAL ? total - REPASO_INICIAL : 0n;
 
-    // Las nuevas, más las que quedaron pendientes de vueltas anteriores.
-    const pendientes = new Set<string>(huerfanas.keys());
-    for (let i = desde; i < total; i++) pendientes.add(i.toString());
-    if (pendientes.size === 0) {
-      escribirMarca(total - 1n);
+    // Las nuevas, más las que quedaron sin resolver de vueltas anteriores.
+    const aMirar = new Set<string>(pendientes);
+    for (let i = desde; i < total; i++) aMirar.add(i.toString());
+    if (aMirar.size === 0) {
+      escribirEstado(total - 1n, aMirar);
       return false;
     }
 
-    for (const id of pendientes) {
-      if (parado) return true;
+    // Se PARTE de que todas siguen pendientes y solo sale la que devuelva un
+    // veredicto de resuelta. Antes era al revés —dentro salvo que alguien se
+    // quejara— y por eso un fallo a mitad equivalía a un éxito.
+    const restantes = new Set<string>(aMirar);
+    for (const id of aMirar) {
+      // `break` y no `return`: hay que guardar lo que sí se llegó a resolver,
+      // y sobre todo lo que no.
+      if (parado) break;
       const taskId = BigInt(id);
+      let veredicto: Veredicto = 'pendiente';
       try {
-        await revisarUna(taskId);
+        veredicto = await revisarUna(taskId);
       } catch (err) {
-        console.error(`[vigilante] #${taskId}: ${err instanceof Error ? err.message : err}`);
+        console.error(
+          `[vigilante] #${taskId}: ${err instanceof Error ? err.message : err} — sigue pendiente`,
+        );
       }
+      if (veredicto === 'resuelta') restantes.delete(id);
     }
-    escribirMarca(total - 1n);
+    escribirEstado(total - 1n, restantes);
     // Habia algo que mirar, aunque no fuera nuestro: no es una vuelta en blanco.
     return true;
   }
 
-  async function revisarUna(taskId: bigint): Promise<void> {
+  async function revisarUna(taskId: bigint): Promise<Veredicto> {
     const task = await deps.panal.getTask(taskId);
     const id = taskId.toString();
 
-    // Ni mía, ni viva: fuera de la lista y a otra cosa.
+    // No es mía: no hay nada que resolver y no hará falta volver a mirarla.
     if (task.worker.toLowerCase() !== deps.yo.toLowerCase()) {
-      huerfanas.delete(id);
-      return;
+      vistas.delete(id);
+      return 'resuelta';
     }
+    // Cerrada en la cadena —entregada, completada, disputada o cancelada—.
+    // ESTA es la única salida buena de la lista: lo dice el escrow, no nosotros.
     if (task.status !== TaskStatus.Open) {
-      huerfanas.delete(id);
+      vistas.delete(id);
       avisadas.delete(id);
-      return;
+      quejadas.delete(id);
+      return 'resuelta';
     }
 
     // Se está trabajando ahora mismo: no es un hueco, es el camino normal. Ni
     // se retoma, ni se avisa de que falte el encargo — lo tiene y lo está
     // usando. El vigilante solo se ocupa de lo que ya no se mueve.
+    //
+    // PERO SIGUE PENDIENTE. Antes esto la sacaba de la lista, y era el mismo
+    // fallo con otro disfraz: si ese trabajo en curso acababa reventando, la
+    // marca ya había pasado por encima y no volvía a mirarla nadie.
     if (deps.enCurso(taskId)) {
-      huerfanas.delete(id);
-      return;
+      vistas.delete(id);
+      return 'pendiente';
     }
 
     // CASO 3: el resultado está calculado y la tarea sigue abierta, así que la
     // entrega no llegó a anclarse. Se reintenta, que es gratis para el cliente
     // y le devuelve una tarea que daba por perdida.
+    //
+    // Si `reentregar` falla, lanza: sube a `repasar`, que la deja pendiente.
     const resultado = deps.resultadoGuardado(taskId);
     if (resultado !== null) {
       console.log(`[vigilante] #${taskId} tenía resultado sin anclar: se reintenta la entrega`);
       await deps.reentregar(taskId, resultado);
-      huerfanas.delete(id);
-      return;
+      vistas.delete(id);
+      return 'resuelta';
     }
 
     // CASO 2: el encargo está guardado pero no hay resultado, o sea que el
@@ -202,26 +310,38 @@ export function arrancarVigilante(deps: VigilanteDeps): { parar: () => void } {
       // otra ejecución y no vale fiarse: si no cuadra con lo que hay en la
       // cadena, trabajar sobre él sería entregar algo que el cliente no pidió.
       if (keccak256(toBytes(brief)) !== task.taskHash) {
-        console.error(
-          `[vigilante] #${taskId} el encargo guardado NO cuadra con el taskHash de la cadena: se ignora`,
-        );
-        huerfanas.delete(id);
-        return;
+        // Pendiente, NO resuelta: el cliente todavía puede reenviar el bueno
+        // por /reenviar y entonces sí se puede trabajar. Se queja una sola vez
+        // para no llenar el log en cada vuelta.
+        if (!quejadas.has(id)) {
+          quejadas.add(id);
+          console.error(
+            `[vigilante] #${taskId} el encargo guardado NO cuadra con el taskHash de la cadena: ` +
+              'no se trabaja sobre él. Que el cliente lo reenvíe.',
+          );
+        }
+        return 'pendiente';
       }
       console.log(`[vigilante] #${taskId} se quedó a medias: se retoma el trabajo`);
-      await deps.trabajar(taskId, brief);
-      huerfanas.delete(id);
-      return;
+      const entregada = await deps.trabajar(taskId, brief);
+      vistas.delete(id);
+      // AQUÍ vivía el segundo fallo: se daba por resuelta sin mirar si lo
+      // estaba. Un modelo que devuelve 429 dos veces seguidas se veía igual
+      // que una entrega perfecta.
+      if (!entregada) {
+        console.log(`[vigilante] #${taskId} no quedó entregada: sigue en la lista para la próxima vuelta`);
+      }
+      return entregada ? 'resuelta' : 'pendiente';
     }
 
     // CASO 1: hay tarea y no hay encargo. Aquí no se puede hacer nada más que
     // avisar: el texto no está en la cadena y adivinarlo sería inventárselo.
-    const visto = huerfanas.get(id);
+    const visto = vistas.get(id);
     if (visto === undefined) {
-      huerfanas.set(id, Date.now());
-      return;
+      vistas.set(id, Date.now());
+      return 'pendiente';
     }
-    if (Date.now() - visto < GRACIA_MS || avisadas.has(id)) return;
+    if (Date.now() - visto < GRACIA_MS || avisadas.has(id)) return 'pendiente';
 
     avisadas.add(id);
     // En cuánto vence, no cuándo. La fecha absoluta se imprimía en UTC junto a
@@ -242,6 +362,9 @@ export function arrancarVigilante(deps: VigilanteDeps): { parar: () => void } {
         ` o desde https://panal.lat/dashboard.\n` +
         `  Si nadie lo hace, el plazo vence ${vence} y el cliente recupera su dinero.`,
     );
+    // Sigue abierta y sin encargo: se queda en la lista hasta que la cadena
+    // diga otra cosa.
+    return 'pendiente';
   }
 
   console.log(`Vigilante activo: repasa cada ${CADA} s (VIGILANTE=off para apagarlo).`);