changebook 0.7.0 → 0.8.0

package/dist/tools.js

@@ -6,312 +6,19 @@
  */
 import { z } from "zod";
 import { execFileAsync, projectNameFor } from "./git.js";
-import { avisoRefutado, contarEnRepo, dondeApareceElSimbolo, dondeComprobarlo, ficherosEnRepo, slugifyProject, unoPorTexto, } from "./guard.js";
-import { SupabaseError } from "./supabase.js";
+import { avisoRefutado, contarEnRepo, dondeApareceElSimbolo, dondeComprobarlo, fueraDelCambio, fichaDelSimbolo, lineasEnRepo, ficherosEnRepo, slugifyProject, unoPorTexto, } from "./guard.js";
+import { canonicalDiffHash } from "./canonical.js";
+import { registrarActionPlan } from "./toolActionPlan.js";
+import { registrarUsage } from "./toolUsage.js";
+import { registrarProjectBrief } from "./toolProjectBrief.js";
 import { coChangePairs } from "./sync.js";
 import { aliasesFor, canonicalizeModuleRows, canonicalModule, etiquetaPorSlug, expandModuleNames, projectIdOf, slugModule, } from "./aliasDeModulo.js";
-const CHARACTER_LIMIT = 25_000;
-/**
- * El contrato temporal de las respuestas del atlas (benchmark 2026-07-20: el
- * agente afirmó un valor revertido porque la nota hablaba en presente). El
- * ancla de deriva de derivaContraHead lo dice con precisión cuando hay árbol
- * y hash; esta línea fija cubre el resto de los casos — nunca las dos a la
- * vez.
- */
-const TEMPORAL_CONTRACT = "Notes describe the code AS OF their date — concrete values (numbers, limits, names) may have changed since. Verify in the code before asserting them.";
-// ── Helpers ───────────────────────────────────────────────────────────────────
-/**
- * Lo que de VERDAD llega al modelo. Espejo de servedCharsOf en
- * supabase/functions/mcp/index.ts.
- *
- * `chars_served` contaba el markdown, y el markdown casi nunca se usa: los
- * tool_result llegan al modelo como el JSON del structuredContent. Solo cuando
- * la respuesta revienta CHARACTER_LIMIT deja de haber JSON y queda el texto.
- * Contar el markdown infravaloraba el gasto un 35%.
- */
-function servedCharsOf(result) {
-    return "structuredContent" in result && result.structuredContent
-        ? JSON.stringify(result.structuredContent).length
-        : (result.content?.[0]?.text?.length ?? 0);
-}
-function errorResult(error) {
-    const message = error instanceof SupabaseError || error instanceof Error
-        ? error.message
-        : String(error);
-    // isError lets the MCP client (and the agent) tell a failed call from a valid
-    // result whose text happens to start with "Error:".
-    return {
-        isError: true,
-        content: [{ type: "text", text: `Error: ${message}` }],
-    };
-}
-function truncate(text) {
-    if (text.length <= CHARACTER_LIMIT)
-        return text;
-    return (text.slice(0, CHARACTER_LIMIT) +
-        "\n\n[Truncated. Use a smaller `limit`, an `offset`, or filters to narrow the result.]");
-}
-// Build a tool result. structuredContent duplicates the rendered text, so when
-// the text has to be truncated we drop it — otherwise the full, unbounded object
-// would be sent anyway and defeat the very CHARACTER_LIMIT that truncated it.
-function toolResult(text, structured) {
-    if (text.length <= CHARACTER_LIMIT) {
-        return {
-            content: [{ type: "text", text }],
-            structuredContent: structured,
-        };
-    }
-    return { content: [{ type: "text", text: truncate(text) }] };
-}
-function fileList(files) {
-    return Array.isArray(files) ? files.map(String) : [];
-}
-// Summary-first excerpts: the stored diff excerpts are the most expensive part
-// of atlas_module_detail (~1.5k chars each), and most calls only need to know
-// WHAT changed. Default to a short preview; `full: true` returns them verbatim.
-const EXCERPT_PREVIEW_LINES = 4;
-const EXCERPT_PREVIEW_CHARS = 320;
-function previewExcerpt(excerpt) {
-    let text = excerpt.split("\n").slice(0, EXCERPT_PREVIEW_LINES).join("\n");
-    if (text.length > EXCERPT_PREVIEW_CHARS) {
-        text = text.slice(0, EXCERPT_PREVIEW_CHARS);
-    }
-    return { text: text.trimEnd(), truncated: text.length < excerpt.length };
-}
-function day(iso) {
-    return iso.slice(0, 10);
-}
-// Pre-edit lookup helpers (mirror of the hosted scope.ts — the npm package
-// must stay self-contained, so these three stay tiny and duplicated).
-// Exported so test/mcpParity.test.ts can pin them equal to the hosted copies:
-// drift would break atlas_file_context on stdio silently (audit M7).
-export function normalizeRepoPath(path) {
-    return path.trim().replace(/^\.\//, "").replace(/^\/+/, "");
-}
-export function fileContainsFilter(path) {
-    return `files=cs.${encodeURIComponent(JSON.stringify([path]))}`;
-}
-export function quotedInList(values) {
-    return values
-        .map((v) => `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`)
-        .join(",");
-}
-export const FILES_CAP = 8;
-const MAX_DEPENDENTS = 6;
-/** Espejo de MODULE_COUNT_WINDOW_ROWS (supabase/functions/mcp/scope.ts).
- *  El mapa de la web dibuja las flechas sobre esta misma ventana: dos
- *  ventanas distintas darían dependencias distintas según se mire el dibujo
- *  o se pregunte al atlas. Paridad fijada en test/radioDeImpacto. */
-const MODULE_GRAPH_WINDOW_ROWS = 1000;
-export function dependentsOf(targets, rows) {
-    // POR SLUG, NO POR toLowerCase(): media normalizacion se lee igual que una
-    // entera (invariante 16). Espejo de supabase/functions/mcp/scope.ts.
-    const etiqueta = etiquetaPorSlug(rows.map((r) => r.module ?? ""));
-    // Memo de slugModule: se llama una vez por fila y por dep. Espejo de
-    // supabase/functions/mcp/scope.ts (medido: 0,510 ms -> 2,698 ms sin esto).
-    const memo = new Map();
-    const slug = (s) => {
-        let v = memo.get(s);
-        if (v === undefined) {
-            v = slugModule(s);
-            memo.set(s, v);
-        }
-        return v;
-    };
-    const graph = new Map();
-    for (const r of rows) {
-        const label = (r.module ?? "").trim();
-        if (!label || graph.has(slug(label)))
-            continue;
-        const deps = Array.isArray(r.deps)
-            ? r.deps.map((d) => (typeof d === "string" ? d.trim() : "")).filter(Boolean)
-            : [];
-        graph.set(slug(label), deps);
-    }
-    const reverse = new Map();
-    for (const r of rows) {
-        const crudo = (r.module ?? "").trim();
-        if (!crudo)
-            continue;
-        const slugFrom = slug(crudo);
-        const from = etiqueta.get(slugFrom) ?? crudo;
-        for (const to of graph.get(slugFrom) ?? []) {
-            const key = slug(to);
-            if (key === slugFrom)
-                continue;
-            const set = reverse.get(key) ?? new Set();
-            set.add(from);
-            reverse.set(key, set);
-        }
-    }
-    const out = new Map();
-    for (const t of targets) {
-        const label = (t ?? "").trim();
-        if (!label)
-            continue;
-        const found = reverse.get(slug(label));
-        if (!found || found.size === 0)
-            continue;
-        out.set(label, [...found].sort((a, b) => a.localeCompare(b)).slice(0, MAX_DEPENDENTS));
-    }
-    return out;
-}
-/**
- * Reincidencia (espejo de supabase/functions/mcp/scope.ts::computeRecidivism —
- * paridad en test/reincidenciaFileContext). Por módulo, nº de problemas de
- * regresión DISTINTOS (count(distinct plain), all-time), solo los con
- * antecedentes (>= 2). Plain distinto, no filas, para que el re-levantado no
- * infle. No se refuta: cuenta historia, no vigencia.
- */
-/**
- * ESPEJO de `RecidivismMap` en supabase/functions/mcp/scope.ts. Un Map de
- * verdad —se itera y se muestra con la etiqueta buena— cuyo `get`/`has`
- * normalizan la clave por slug antes de buscar, para que ningún consumidor
- * tenga que acordarse de canonicalizar. Ver allí el razonamiento entero.
- */
-export class RecidivismMap extends Map {
-    #porSlug = new Map();
-    set(clave, valor) {
-        this.#porSlug.set(slugModule(clave), valor);
-        return super.set(clave, valor);
-    }
-    get(clave) {
-        return super.get(clave) ?? this.#porSlug.get(slugModule(clave));
-    }
-    has(clave) {
-        return super.has(clave) || this.#porSlug.has(slugModule(clave));
-    }
-}
-export function computeRecidivism(rows) {
-    // Agrupado por slug y presentado con la etiqueta representante: si las
-    // alertas de un módulo partido están escritas con las dos grafías, sus
-    // regresiones distintas son las de UN módulo, no las de dos.
-    const etiqueta = etiquetaPorSlug(rows.map((r) => r.module ?? ""));
-    const plainsByModule = new Map();
-    for (const r of rows) {
-        // SOLO LAS CONFIRMADAS. Hasta el 2026-08-02 esto contaba TODA fila de
-        // `regression_alerts`, o sea avisos que el propio atlas se generó: sumaba
-        // los confirmados, los que el dueño refutó, los que se cerraron solos al
-        // re-tocar el módulo y los 79 que son anteriores al campo `resolution`.
-        // Medido en producción: decía 110 y las confirmadas eran 20 — «Análisis de
-        // cambios» salía con 13 y tenía CERO.
-        //
-        // La migración que añadió `resolution` (20260725100000) dice en su propio
-        // comentario que existe para impedir «el número bonito y falso». Este
-        // contador nunca lo adoptó. Ahora sí.
-        //
-        // `fixed` lo escribe el agente que actuó sobre el aviso, no un oráculo
-        // independiente, así que sigue siendo autocertificado — pero es la mejor
-        // etiqueta que hay, y desde luego mejor que no mirar.
-        if ((r.resolution ?? "").trim().toLowerCase() !== "fixed")
-            continue;
-        const crudo = (r.module ?? "").trim();
-        const p = (r.plain ?? "").trim();
-        if (!crudo || !p)
-            continue;
-        const m = etiqueta.get(slugModule(crudo)) ?? crudo;
-        const set = plainsByModule.get(m) ?? new Set();
-        set.add(p);
-        plainsByModule.set(m, set);
-    }
-    const out = new RecidivismMap();
-    for (const [m, set] of plainsByModule) {
-        if (set.size >= 2)
-            out.set(m, set.size);
-    }
-    return out;
-}
-export function filesUnionByChange(rows, cap = FILES_CAP) {
-    const acc = new Map();
-    for (const r of rows) {
-        if (!Array.isArray(r.files))
-            continue;
-        let list = acc.get(r.changelog_id);
-        if (!list) {
-            list = [];
-            acc.set(r.changelog_id, list);
-        }
-        for (const f of r.files) {
-            if (typeof f === "string" && f.length > 0 && !list.includes(f)) {
-                list.push(f);
-            }
-        }
-    }
-    const out = new Map();
-    for (const [id, list] of acc) {
-        out.set(id, {
-            files: list.slice(0, cap),
-            more: Math.max(0, list.length - cap),
-        });
-    }
-    return out;
-}
-// Espejo de supabase/functions/mcp/scope.ts (paridad en
-// test/espejoDeCommits.test.ts): aliases post-squash del mismo contenido,
-// para que el hash citado exista en el main del consultante.
-export function commitAliasesShort(raw) {
-    if (!Array.isArray(raw))
-        return [];
-    return raw
-        .filter((h) => typeof h === "string" && /^[0-9a-f]{7,64}$/i.test(h))
-        .map((h) => h.slice(0, 7));
-}
-export function commitLabel(hash, aliasesRaw) {
-    const corto = hash?.slice(0, 7) ?? null;
-    if (!corto)
-        return null;
-    const aliases = commitAliasesShort(aliasesRaw);
-    return aliases.length > 0 ? `${corto} (=${aliases.join(",")})` : corto;
-}
-export const FILE_COMMITS_CAP = 5;
-export function recentCommitsForFile(changelogIds, commitById, cap = FILE_COMMITS_CAP) {
-    const all = changelogIds
-        .map((id) => commitById.get(id))
-        .filter((c) => Boolean(c));
-    return { commits: all.slice(0, cap), more: Math.max(0, all.length - cap) };
-}
-// Consultation metering (never billing): each successful read leaves a row in
-// atlas_reads so the web can show "your agent consulted the atlas N times".
-// Best-effort and non-blocking — metering must never break or slow a read.
-// user_id is filled server-side (column default auth.uid()).
-function recordRead(db, tool, projectFilter, charsServed, latencyMs) {
-    const projectId = /project_id=eq\.([0-9a-f-]+)/.exec(projectFilter)?.[1] ?? null;
-    void db
-        .insertRow("atlas_reads", {
-        project_id: projectId,
-        tool,
-        source: "stdio",
-        chars_served: charsServed,
-        // Latencia del handler (encargo 0dbbfbf4): nullable a propósito — es
-        // metering, jamás contrato, y un servidor viejo simplemente no la manda.
-        ...(latencyMs !== undefined
-            ? { latency_ms: Math.max(0, Math.min(Math.round(latencyMs), 600000)) }
-            : {}),
-    })
-        .catch(() => { });
-}
-/** PostgREST `or=(...ilike...)` needs the pattern URL-encoded once. */
-function ilikePattern(search) {
-    return encodeURIComponent(`*${search.replace(/[%*,()]/g, " ").trim()}*`);
-}
-/**
- * ¿El árbol de trabajo donde corre este servidor ES el proyecto consultado?
- *
- * Solo entonces un grep local puede refutar una alerta: la tool recibe
- * `project` como argumento, pero el proceso corre donde el cliente lo arrancó.
- * En un repo válido pero AJENO, un símbolo ausente da un 0 REAL (no null) y
- * avisoRefutado con expect='present' lo tomaría como refutación — silenciar
- * una alerta verdadera por mirar donde no era es peor que el ruido.
- *
- * La identidad sale de `projectNameFor`, la MISMA que usan el guardián, el hook
- * y sync: `CHANGEBOOK_PROJECT`, si no el nombre del árbol PRINCIPAL, y solo como
- * último recurso el basename del cwd. Usar `path.basename(cwd)` a secas era el
- * fallo: en un worktree enlazado el basename es el del worktree (`seo-wt`,
- * `wt-3`…), NO el del repo, así que el grep de refutación y el ancla temporal se
- * apagaban en todo worktree aunque fuera el mismo proyecto. `projectNameFor` ya
- * resolvió esto para el resto del CLI el 2026-07-25; este gate se había quedado
- * atrás.
- */
+import { RO, TEMPORAL_CONTRACT, day, errorResult, fileList, ilikePattern, previewExcerpt, servedCharsOf, toolResult, } from "./respuestas.js";
+import { MODULE_GRAPH_WINDOW_ROWS, aggregateFileContext, commitAliasesShort, computeRecidivism, dependentsOf, fileContainsFilter, filesUnionByChange, normalizeRepoPath, projectIdFromFilter, quotedInList, recentCommitsForFile, recordRead, resolveAlertFilter, } from "./agregados.js";
+// Los agregados puros viven en `agregados.ts` desde el 09/08 (ver su cabecera).
+// Se RE-EXPORTAN aqui porque `tools.ts` sigue siendo la superficie publica que
+// importan los contratos: mover el codigo no tiene por que mover sus imports.
+export * from "./agregados.js";
 function cwdEsElProyecto(project) {
     return (slugifyProject(projectNameFor(process.cwd())) ===
         slugifyProject(project.trim()));
@@ -343,6 +50,12 @@ export async function derivaContraHead(dir, hash) {
 }
 // ── Registration ──────────────────────────────────────────────────────────────
 export function registerTools(server, db) {
+    // El brief vive en su propio fichero (son 300 lineas y `tools.ts` ya iba
+    // por 1.900). Se registra desde aqui para que `registerTools` siga siendo
+    // el UNICO sitio donde se decide que herramientas sirve este servidor.
+    registrarProjectBrief(server, db);
+    registrarActionPlan(server, db);
+    registrarUsage(server, db);
     server.registerTool("atlas_recent_changes", {
         title: "Recent ChangeBook changes",
         description: `List the most recent analyzed code changes from the ChangeBook changelog (newest first).
@@ -766,33 +479,13 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                 // canonicalizar después dejaría el mismo módulo partido en dos
                 // entradas con la mitad de los cambios cada una.
                 const rows = canonicalizeModuleRows(rowsCrudas, aliases);
-                const byModule = new Map();
-                // Commits que tocaron ESTE archivo, del más nuevo al más viejo,
-                // deduplicados (un mismo análisis puede traer varias filas de
-                // change_module para el mismo archivo). El hash lo resuelve la
-                // consulta batcheada de abajo; aquí solo se guarda el orden.
-                const changelogIds = [];
-                for (const row of rows) {
-                    if (!changelogIds.includes(row.changelog_id)) {
-                        changelogIds.push(row.changelog_id);
-                    }
-                    const name = (row.module ?? "").trim();
-                    if (!name)
-                        continue;
-                    const existing = byModule.get(name);
-                    if (existing)
-                        existing.changes += 1;
-                    else {
-                        byModule.set(name, {
-                            module: name,
-                            risk: row.risk,
-                            changes: 1,
-                            last_changed: day(row.created_at),
-                            last_note: row.note,
-                        });
-                    }
-                }
-                return { file, modules: [...byModule.values()], changelogIds };
+                // ESTE BUCLE VIVÍA AQUÍ ESCRITO A MANO y agrupaba por nombre crudo,
+                // así que `Núcleo` y `Nucleo` salían como dos módulos distintos del
+                // mismo fichero, con la mitad de los cambios cada uno. Ahora lo hace
+                // `aggregateFileContext`, que agrupa por slug igual que el
+                // hospedado y que el brief. Los `changelogIds` (orden de commits,
+                // del más nuevo al más viejo, deduplicados) salen de ahí también.
+                return aggregateFileContext(file, rows);
             }));
             // Los nombres YA canonicalizados: es lo que se enseña y con lo que se
             // agrupa. Pero las consultas de abajo filtran EN EL SERVIDOR por
@@ -837,7 +530,7 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                     // "sin_declarar" siempre) ni se sirve la línea NOT CHECKABLE
                     // HERE, que es la única forma de que un aviso sobre producción
                     // no se compruebe con un grep del repo. Ver guard.ts.
-                    `regression_alerts?select=module,plain,evidence_symbol,evidence_expect,evidence_scope,evidence_line&resolved_at=is.null&module=in.(${encodeURIComponent(quotedInList(nombresParaConsultar))})&order=created_at.desc&limit=10` +
+                    `regression_alerts?select=module,plain,evidence_symbol,evidence_expect,evidence_scope,evidence_line,evidence_in_diff&resolved_at=is.null&module=in.(${encodeURIComponent(quotedInList(nombresParaConsultar))})&order=created_at.desc&limit=10` +
                         pf)
                     : Promise.resolve([]),
                 // Constantes vigiladas (espejo del hospedado): el valor VIGENTE con
@@ -928,6 +621,11 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
             const localizada = enElProyecto
                 ? (a) => dondeApareceElSimbolo(a, (s) => ficherosEnRepo(process.cwd(), s))
                 : () => null;
+            // Mismo gate `enElProyecto` que la de arriba, y por lo mismo: en un repo
+            // ajeno el grep contestaría sobre un árbol que no es el del aviso.
+            const fichada = enElProyecto
+                ? (a) => fichaDelSimbolo(a, (s) => lineasEnRepo(process.cwd(), s))
+                : () => null;
             // Se construye la lista ANTES de renderizar para poder dejar una linea
             // por texto: dos avisos con la misma frase se leen como una repeticion
             // aunque por dentro sean afirmaciones opuestas, y sobre dos frases
@@ -947,6 +645,19 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
                         `\n    → CHECKED NOW: "${(a.evidence_symbol ?? "").trim()}" still appears in ${donde.join(", ")}` +
                             ` — alert expects it gone: either a reference was missed, or the alert is stale`;
                 }
+                // ANTES que la ficha, y el orden es la mitad del mensaje: primero que
+                // el modelo habló de código que no vio, después dónde vive ese código
+                // de verdad. Al revés se lee como un dato de localización suelto.
+                const fuera2 = fueraDelCambio(a);
+                if (fuera2)
+                    extra += `\n    → NOT IN THE DIFF: ${fuera2}`;
+                // La otra mitad, y la que cubre el caso DOMINANTE: un aviso 'present'
+                // cuyo símbolo sigue ahí (el 81% de los de FacelessOS) no se puede
+                // refutar con un conteo, pero sí se puede CONTESTAR diciendo dónde
+                // vive y si se exporta. Ver `fichaDelSimbolo`.
+                const ficha = fichada(a);
+                if (ficha)
+                    extra += `\n    → CHECKED NOW: ${ficha}`;
                 // El repo no puede contestar esta afirmacion: se dice, en vez de
                 // dejar que se compruebe donde no era.
                 if (fuera)
@@ -1085,5 +796,294 @@ Returns (structured): { files: [{ file, modules: [{ module, risk, changes, last_
             return errorResult(error);
         }
     });
+    // ── atlas_resolve_alert ─────────────────────────────────────────────────────
+    //
+    // PORTADA DEL HOSPEDADO EL 08/08. Existía allí desde el 24/07 (`5237eb1`) y
+    // nunca llegó aquí, mientras `sync.ts` —de este mismo paquete— escribía en el
+    // bloque de CLAUDE.md «al comprobar o arreglar un aviso: `atlas_resolve_alert`».
+    // Quien instalaba por npm leía la orden y no tenía con qué cumplirla: ni esta
+    // tool ni subcomando de CLI equivalente. Resultado: los avisos solo podían
+    // quedarse abiertos, y una cuenta sin refutaciones se lee igual que una cuenta
+    // cuyos avisos eran todos buenos (invariante 17).
+    //
+    // La descripción y el esquema son los del hospedado a propósito, incluido el
+    // `verdict` SIN DEFECTO: cerrar sin juzgar contaría como acierto del generador
+    // e inflaría la precisión que el producto publica.
+    server.registerTool("atlas_resolve_alert", {
+        title: "Resolve a regression alert",
+        description: "Close this project's open regression alert(s) once you have judged them, so the analysis stops re-raising them and stops re-queuing the owner's task. Call it with `verdict:\"fixed\"` when the alert was RIGHT and you fixed or confirmed the risk, and with `verdict:\"dismissed\"` when you CHECKED IT AND IT WAS WRONG — a false alarm, already handled, or about code that is deliberately that way. Refuting is as valuable as confirming: the accuracy this product reports needs both, and an alert you silently confirm to get rid of it makes that number a lie. Identify them by `module` (closes every open alert on that module) and optionally narrow with `symbol` (the evidence symbol the alert hangs on). Judge only what you actually looked at; it is reversible from the web. " +
+            "project: the repo you are working in (folder name or slug).",
+        inputSchema: {
+            project: z.string().min(1).max(120),
+            module: z.string().min(1).max(200),
+            symbol: z.string().min(1).max(120).optional(),
+            verdict: z
+                .enum(["fixed", "dismissed"])
+                .describe("REQUIRED. fixed = the alert was right and you fixed or confirmed it. " +
+                "dismissed = you checked it and it was wrong (false alarm, already " +
+                "handled, or deliberate). There is no default on purpose: closing an " +
+                "alert without judging it would count as the generator being right " +
+                "and inflate the accuracy this product publishes."),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ project, module, symbol, verdict }) => {
+        try {
+            const pf = await db.projectFilterFor(project);
+            const projectId = projectIdFromFilter(pf);
+            if (!projectId) {
+                // Sin uuid no se construye un filtro acotado, y un PATCH mal acotado
+                // sobre esta tabla es justo lo que el grant por columna existe para
+                // que no pase. Se para antes de escribir.
+                return toolResult(`Could not resolve which project "${project}" is. Pass the repo folder name or its ChangeBook slug.`, { resolved: 0 });
+            }
+            const filtro = resolveAlertFilter({ projectId, module, symbol });
+            // SE LEE ANTES DE ESCRIBIR, y no por cortesía. Es lo único que permite
+            // distinguir después «no había nada abierto» de «no me dejaron
+            // escribir»: las dos cosas terminan en cero filas escritas y son
+            // diagnósticos opuestos. El 25/07 esa confusión dejó tres caminos
+            // fallando en silencio con 42501 durante días.
+            const abiertas = await db.rest(`regression_alerts?select=id,plain&${filtro}&order=created_at.desc&limit=50`);
+            if (abiertas.length === 0) {
+                return toolResult(`No open alert on "${module}"${symbol ? ` with symbol "${symbol}"` : ""}. Nothing to resolve.`, { resolved: 0, module, symbol: symbol ?? null, items: [] });
+            }
+            const escritas = await db.patchRowsReturning("regression_alerts", `${filtro}&id=in.(${abiertas.map((a) => a.id).join(",")})`, {
+                resolved_at: new Date().toISOString(),
+                resolution: verdict,
+                // QUIÉN lo dicta. El agente tiene interés en cerrar —el aviso le
+                // quita el encargo de encima— así que su juicio no puede contarse
+                // junto al de una persona ni al del grep. Ver la migración
+                // 20260802120000, que además es la que mete esta columna en el grant.
+                resolution_by: "agent",
+            });
+            if (escritas.length === 0) {
+                // Había filas abiertas y no se escribió ninguna: eso NO es "nada que
+                // cerrar", es una escritura rechazada. Se devuelve como error para
+                // que el agente lo vea, en vez de un {resolved: 0} tranquilizador.
+                return errorResult(new Error(`Found ${abiertas.length} open alert(s) on "${module}" but the update wrote none. ` +
+                    `This is a refused write, not an empty match — most likely the column grant on ` +
+                    `regression_alerts (resolved_at, resolution, resolution_by) or an RLS policy. ` +
+                    `Nothing was closed; resolve it from the web and check the grant.`));
+            }
+            const parcial = escritas.length < abiertas.length
+                ? ` (${abiertas.length - escritas.length} of ${abiertas.length} could not be written — check the column grant)`
+                : "";
+            return toolResult(`${verdict === "dismissed" ? "Dismissed" : "Confirmed and closed"} ${escritas.length} alert(s) on "${module}"${symbol ? ` (symbol ${symbol})` : ""} — recorded as ${verdict}${parcial}. They will stop being re-raised, and the owner's auto-task for them will stop re-queuing.`, {
+                resolved: escritas.length,
+                matched: abiertas.length,
+                module,
+                symbol: symbol ?? null,
+                items: escritas.map((r) => r.plain),
+            });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // ── atlas_record_change ─────────────────────────────────────────────────────
+    //
+    // PORTADA DEL HOSPEDADO EL 09/08. Existía allí desde el 16/07 (`1832a13`) y el
+    // bloque de CLAUDE.md la pide después de cada commit, pero aquí no estaba.
+    //
+    // ⚠ EN UNA INSTALACIÓN CON HOOK ESTO ES REDUNDANTE, y conviene decirlo en vez
+    // de venderlo: el `post-commit` ya registra cada commit solo, leyendo el diff
+    // de git, y ese camino NO puede descasar del hash. Esta tool existe para el
+    // caso sin hook y para cambios sin commit. La descripción del hospedado se
+    // mantiene palabra por palabra —los dos servidores tienen que pedir lo mismo—
+    // pero el `summary` importa aquí igual: enruta el análisis a un modelo mucho
+    // más barato.
+    const MAX_TOOL_DIFF = 60_000; // espejo de MAX_DIFF_CHARACTERS del servidor
+    server.registerTool("atlas_record_change", {
+        title: "Record a change in the atlas",
+        description: "Call this right AFTER you make or commit a change, so the atlas stays current. Send the unified diff (e.g. `git show <ref>` or `git diff`) plus the commit hash and ISO date when available. ChangeBook's own AI analyzes it (business impact, modules, risk) — you only deliver the diff. ALWAYS pass `project` = the repo folder name you are working in (the atlas is per-project; a new name creates the project). ALWAYS include `summary`: 2-5 sentences in your own words on what changed and why (intent, user-visible effect, risks) — you already know this, and it routes the analysis to a much cheaper model. Re-sending the same commit is a free no-op.",
+        inputSchema: {
+            diff: z.string().min(20).max(MAX_TOOL_DIFF),
+            commit_hash: z
+                .string()
+                .regex(/^[0-9a-f]{7,64}$/i)
+                .optional(),
+            committed_at: z.string().datetime({ offset: true }).optional(),
+            project: z.string().min(1).max(120),
+            summary: z.string().min(20).max(2_400).optional(),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ diff, commit_hash, committed_at, project, summary }) => {
+        try {
+            const { status, body } = await db.invokeFunction("analyze-diff", {
+                compressedDiff: diff,
+                rawDiffChars: diff.length,
+                // El diff del agente llega crudo (git show): su hash canónico es la
+                // identidad que alinea el dedup con el hook y el webhook. Si esto
+                // divergiera, el mismo commit entraría dos veces por dos caminos.
+                rawContentHash: canonicalDiffHash(diff),
+                commitHash: commit_hash,
+                committedAt: committed_at,
+                projectName: project,
+                agentSummary: summary,
+            });
+            if (status >= 400) {
+                return errorResult(body.error ?? `analysis failed (${status})`);
+            }
+            const modules = Array.isArray(body.modules) ? body.modules.length : 0;
+            // CANAL PUSH: los avisos que ESTE cambio acaba de levantar vuelven en el
+            // acto, sin esperar a que alguien los pida. Reportas un cambio y, si toca
+            // algo que rompe un contrato del atlas, te enteras aquí mismo.
+            const warnings = Array.isArray(body.regressionWarnings)
+                ? body.regressionWarnings.filter((w) => w && typeof w.plain === "string")
+                : [];
+            const warnBlock = warnings.length > 0
+                ? `\n\n⚠ Este cambio levantó ${warnings.length} aviso${warnings.length === 1 ? "" : "s"} de regresión — DÍSELO al usuario y verifícalo:\n` +
+                    warnings
+                        .map((w) => `  · ${w.module ? `[${w.module}] ` : ""}${w.plain}`)
+                        .join("\n")
+                : "";
+            return toolResult(`Recorded in the atlas.\n` +
+                `- Impact: ${body.summary ?? "(already imported — deduped)"}\n` +
+                `- Modules touched: ${modules}` +
+                (body.credits
+                    ? `\n- Analyses used: ${body.credits.used}/${body.credits.limit}`
+                    : "") +
+                warnBlock, {
+                recorded: true,
+                summary: body.summary ?? null,
+                modules_touched: modules,
+                regression_warnings: warnings,
+            });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // ── atlas_pending_tasks ─────────────────────────────────────────────────────
+    //
+    // PORTADA DEL HOSPEDADO EL 09/08. La cola de encargos ya se leía en este
+    // paquete —`fetchBriefSection` la mete en el bloque de CLAUDE.md— pero el
+    // agente no tenía forma de pedir el CUERPO de uno, que es lo único que
+    // permite atacarlo. El bloque decía «cola viva: `atlas_pending_tasks`» y esa
+    // tool no existía aquí.
+    //
+    // Se usa la RPC `list_agent_tasks` y no un select: es `security definer` y ya
+    // acota por dueño, así que no hay que replicar aquí la autorización.
+    server.registerTool("atlas_pending_tasks", {
+        title: "Tasks the owner queued for the agent",
+        description: "Pending tasks the owner queued for YOU. Returns id, title and a short excerpt; pass `task_id` for one task's full body, context and done-criterion. Tell the user which one you picked and wait for their OK before starting; close it with atlas_complete_task. " +
+            "project: the repo you are working in (folder name or slug).",
+        inputSchema: {
+            project: z.string().min(1).max(120),
+            limit: z.number().int().min(1).max(20).default(10),
+            task_id: z.string().uuid().optional(),
+        },
+        annotations: RO,
+    }, async ({ project, limit, task_id }) => {
+        const t0 = Date.now();
+        try {
+            const pf = await db.projectFilterFor(project);
+            const projectId = projectIdFromFilter(pf);
+            if (!projectId) {
+                return toolResult(`No pending tasks for "${project}".`, { tasks: [] });
+            }
+            const todas = await db.callRpc("list_agent_tasks", {
+                p_project_id: projectId,
+            });
+            const rows = (task_id
+                ? todas.filter((t) => t.id === task_id)
+                : todas.filter((t) => t.status === "pending"))
+                .sort((a, b) => a.created_at.localeCompare(b.created_at))
+                .slice(0, task_id ? 1 : limit);
+            if (rows.length === 0) {
+                const salida = toolResult(task_id
+                    ? `No task ${task_id} in ${project}.`
+                    : `No pending tasks for ${project}.`, { tasks: [], project });
+                recordRead(db, "atlas_pending_tasks", pf, servedCharsOf(salida), Date.now() - t0);
+                return salida;
+            }
+            // LA LISTA DEVUELVE UN EXTRACTO, no el cuerpo entero. Medido el 19/07 en
+            // el hospedado: 10 encargos completos son ~26.000 chars, y un resultado
+            // se reenvía al modelo en cada petición posterior de la sesión — hasta
+            // 20 relecturas, ~104.000 tokens amortizados por UNA llamada. El agente
+            // ataca uno y arrastra los otros nueve sin usarlos.
+            //
+            // 150 chars y no un título pelado: los títulos automáticos son casi
+            // todos «[Auto] Riesgo detectado en <módulo>» y se repiten, así que sin
+            // una línea de contexto el agente abre dos o tres cuerpos y sale más
+            // caro que no haber recortado.
+            const EXTRACTO_CHARS = 150;
+            const resumen = (body) => {
+                const limpio = body
+                    .split("\n")
+                    .filter((l) => l.trim() && !l.startsWith("#"))
+                    .join(" ")
+                    .trim();
+                return limpio.length > EXTRACTO_CHARS
+                    ? `${limpio.slice(0, EXTRACTO_CHARS)}…`
+                    : limpio;
+            };
+            const text = rows
+                .map((t, i) => task_id
+                ? `[${t.id}] ${t.title} — queued ${t.created_at.slice(0, 10)}\n${t.body}`
+                : `${i + 1}. [${t.id}] ${t.title}` +
+                    ` — queued ${t.created_at.slice(0, 10)}\n   ${resumen(t.body)}`)
+                .join("\n\n");
+            const salida = toolResult(`Pending tasks for ${project} (oldest first):\n\n${text}`, {
+                project,
+                tasks: rows.map((t) => ({
+                    id: t.id,
+                    title: t.title,
+                    ...(task_id ? { body: t.body } : { excerpt: resumen(t.body) }),
+                    created_at: t.created_at,
+                })),
+            });
+            recordRead(db, "atlas_pending_tasks", pf, servedCharsOf(salida), Date.now() - t0);
+            return salida;
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // ── atlas_complete_task ─────────────────────────────────────────────────────
+    //
+    // Se cierra por la RPC `resolve_agent_task` y NO con un PATCH a mano, y esa es
+    // la diferencia que importa: su UPDATE dispara el trigger
+    // `agent_tasks_close_alerts`, que cierra además la alerta asociada. Un PATCH
+    // directo cerraría el encargo y dejaría el aviso abierto para siempre — el
+    // encargo desaparecería de la cola y el aviso seguiría re-encolándolo.
+    server.registerTool("atlas_complete_task", {
+        title: "Close a queued task",
+        description: "Mark a task from atlas_pending_tasks as done (or dismissed if it no longer applies). Pass the task id. Closing an already-closed task is a no-op.",
+        inputSchema: {
+            id: z.string().uuid(),
+            status: z.enum(["done", "dismissed"]).default("done"),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ id, status }) => {
+        try {
+            // La RPC devuelve si tocó alguna fila. `false` NO es un error: es un
+            // encargo ya cerrado o ajeno, y se dice tal cual en vez de fingir éxito.
+            const closed = await db.callRpc("resolve_agent_task", {
+                p_id: id,
+                p_status: status,
+            });
+            return toolResult(closed
+                ? `Task ${id} marked as ${status}.`
+                : `Task ${id} was not pending (already closed, or not yours) — nothing changed.`, { closed, status });
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
 }
 //# sourceMappingURL=tools.js.map