changebook 0.4.7 → 0.4.9

package/dist/impact.js

@@ -0,0 +1,512 @@
+/**
+ * `changebook impact` — el radio de impacto, EMPUJADO. Un hook `PreToolUse` de
+ * Claude Code que, justo antes de que el agente escriba en un archivo, le mete
+ * en contexto quién depende de lo que está a punto de tocar.
+ *
+ * POR QUÉ EXISTE, medido y no supuesto:
+ *
+ * El 2026-07-26, la tarea T4 del benchmark («vas a cambiar el comportamiento de
+ * computeRecidivism, ¿qué más hay que revisar?») se corrió con el atlas
+ * instalado y disponible. El agente hizo 32 turnos de grep, gastó 1.464.591
+ * tokens y llamó al atlas CERO veces: `atlas_adoption: 0`. El radio de impacto
+ * —desplegado, testado y en producción— fue invisible.
+ *
+ * La lección no es que faltara una tool. Es que un canal que depende de que el
+ * agente se acuerde de usarlo es un canal que se puede ignorar, y quien programa
+ * a base de «hazme esto» no pregunta nada: no hay turno en el que decida
+ * orientarse. Los disparadores literales de `sync.ts` mueven la aguja (60→100%
+ * medido el 2026-07-21) pero no la clavan: siguen necesitando que el agente
+ * reconozca una frase.
+ *
+ * Este canal no lo necesita. Salta porque va a editar, y punto.
+ *
+ * TRES REGLAS, y las tres son de supervivencia del producto:
+ *
+ *  1. NUNCA bloquea. Se emite `additionalContext` y nada más — sin
+ *     `permissionDecision`, así que el sistema de permisos del usuario decide
+ *     como si no estuviéramos. Un hook que puede tumbar una edición se
+ *     desinstala el día que se equivoca.
+ *  2. NUNCA cuesta tiempo perceptible. Corre antes de CADA edición, así que la
+ *     red se paga una vez cada CACHE_TTL_MS y el resto de las ediciones son una
+ *     lectura de disco. Con presupuesto duro por encima: pasado eso, silencio.
+ *  3. NUNCA repite. Un aviso idéntico en las 20 ediciones seguidas del mismo
+ *     archivo es ruido que se paga en tokens y que entrena al agente a
+ *     ignorarlo. Se avisa una vez por (sesión, archivo).
+ *
+ * Y una cuarta que es la que hace que se lea: SILENCIO cuando no hay nada que
+ * decir. Sin dependientes, sin alerta abierta y sin reincidencia, no se emite
+ * una sola letra.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { presupuestoDeTiempo } from "./context.js";
+import { execFileAsync, gitPath } from "./git.js";
+import { avisoRefutado, contarEnRepo, slugifyProject, } from "./guard.js";
+import { computeRecidivism, dependentsOf } from "./tools.js";
+/**
+ * Techo duro del camino crítico. Más corto que el de `context` (2 s) porque
+ * este corre por edición y no por sesión: 20 ediciones × 2 s serían 40 s de
+ * impuesto sobre el bucle que este producto dice acelerar.
+ */
+const IMPACT_TIMEOUT_MS = 1_200;
+/** Igual que el guardián: las alertas se mueven a velocidad de análisis. */
+const CACHE_TTL_MS = 5 * 60_000;
+/**
+ * Ventana del grafo. Espejo de MODULE_GRAPH_WINDOW_ROWS en tools.ts: dos
+ * ventanas distintas darían dependientes distintos según se pregunte o se
+ * empuje, y el agente no tiene forma de saber cuál de las dos le mintió.
+ */
+const GRAPH_WINDOW_ROWS = 1_000;
+/** Tope de filas de alertas; alimenta reincidencia (all-time) y abiertas. */
+const ALERT_WINDOW_ROWS = 500;
+/** Un archivo vuelve a avisar si se vuelve a él mucho después. */
+const SEEN_TTL_MS = 30 * 60_000;
+/** Cota del archivo de estado: es una nota, no un historial. */
+const SEEN_MAX = 200;
+/** Cuántos módulos se describen si el archivo pertenece a varios. */
+const MAX_MODULES = 3;
+/** Tope de greps de refutación: son síncronos y el techo no los desaloja. */
+const MAX_REFUTACIONES = 3;
+export const IMPACT_HOOK = {
+    event: "PreToolUse",
+    // Mismo `2>/dev/null || true` que CONTEXT_HOOK y por lo mismo: un
+    // `changebook` que no está en el PATH de un compañero no puede convertirse en
+    // un hook que parece roto en cada edición.
+    command: "changebook impact 2>/dev/null || true",
+    marker: "changebook impact",
+    // Las cuatro tools que escriben en un archivo. El matcher es lo que evita
+    // arrancar un proceso por cada Read, Grep o Bash del agente.
+    matcher: "Edit|Write|MultiEdit|NotebookEdit",
+};
+/**
+ * La(s) ruta(s) que la tool va a escribir. `file_path` cubre Edit, Write y
+ * MultiEdit; `notebook_path` cubre NotebookEdit. Se devuelve lista porque el
+ * contrato puede crecer, no porque hoy haya dos.
+ */
+export function pathsFromPayload(payload) {
+    const input = payload.tool_input ?? {};
+    return [input.file_path, input.notebook_path]
+        .filter((v) => typeof v === "string" && v.trim().length > 0)
+        .map((v) => v.trim());
+}
+/**
+ * Ruta con los enlaces simbólicos resueltos, incluso si la ruta no existe.
+ *
+ * No es defensa preventiva: sin esto el hook callaba SIEMPRE en macOS. `git
+ * rev-parse --show-toplevel` devuelve la ruta real (`/private/var/…`) y el
+ * payload del hook trae la que se usó para llegar (`/var/…`, que es un enlace al
+ * anterior). Son el mismo directorio, pero `path.relative` entre las dos daba
+ * `../../…`, la ruta se descartaba por «caer fuera del árbol», y no se avisaba
+ * de nada nunca. Fallo real, cazado por los tests el 2026-07-26.
+ *
+ * Sube hasta el primer ancestro que existe y recompone el resto, porque
+ * `realpathSync` falla con lo inexistente y con `Write` no tiene por qué existir
+ * ni el archivo ni sus carpetas.
+ */
+function rutaRealProfunda(p) {
+    const abs = path.resolve(p);
+    const cola = [];
+    let actual = abs;
+    for (;;) {
+        try {
+            const real = fs.realpathSync(actual);
+            return cola.length > 0 ? path.join(real, ...cola.reverse()) : real;
+        }
+        catch {
+            const padre = path.dirname(actual);
+            if (padre === actual)
+                return abs; // se llegó a la raíz sin resolver nada
+            cola.push(path.basename(actual));
+            actual = padre;
+        }
+    }
+}
+/**
+ * Ruta absoluta (lo que manda el hook) → ruta relativa al repo (lo que guarda
+ * el atlas). `null` cuando queda fuera del árbol: un archivo de /tmp o del home
+ * no tiene módulo, y colarlo como ruta con `../` produciría cero coincidencias
+ * de forma silenciosa.
+ */
+export function repoRelative(toplevel, filePath) {
+    const raiz = rutaRealProfunda(toplevel);
+    const abs = path.isAbsolute(filePath)
+        ? rutaRealProfunda(filePath)
+        : path.resolve(raiz, filePath);
+    const rel = path.relative(raiz, abs);
+    if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    // El atlas guarda rutas de git: siempre con "/", también en Windows.
+    return rel.split(path.sep).join("/");
+}
+/**
+ * ¿Merece este módulo un aviso?
+ *
+ * Es LA decisión del archivo. Se dice algo solo cuando hay algo que el agente
+ * no puede deducir del archivo que tiene delante: quién depende de él (no está
+ * escrito en ninguna parte del código), una alerta abierta (historia), o
+ * reincidencia (historia). El riesgo por sí solo NO cuenta: "risk: medium" en
+ * cada edición es exactamente el ruido que hace que se deje de leer.
+ */
+export function valeLaPena(m) {
+    return (m.dependents.length > 0 || m.alerts.length > 0 || m.priorRegressions >= 2);
+}
+/**
+ * El texto que se inyecta. Deliberadamente calcado a `atlas_file_context`
+ * ("↘ DEPENDS ON THIS", "⚠ OPEN ALERT", "prior regressions"): el agente ya sabe
+ * qué hacer con esas palabras porque las ve cuando pregunta él. Dos redacciones
+ * para el mismo hecho serían dos hechos para él.
+ */
+export function impactText(file, modules) {
+    const lines = [`⚠ ChangeBook — impact radius of ${file}, before you edit it:`];
+    for (const m of modules.slice(0, MAX_MODULES)) {
+        // El riesgo se nombra solo cuando es alto: ver valeLaPena.
+        const alto = m.risk === "high" || m.risk === "hotspot";
+        lines.push(`- Module **${m.module}**` +
+            (alto ? ` · risk: ${m.risk}` : "") +
+            (m.priorRegressions >= 2
+                ? ` · ⚠ ${m.priorRegressions} prior regressions`
+                : ""));
+        if (m.dependents.length > 0) {
+            lines.push(`  - ↘ DEPENDS ON THIS: ${m.dependents.join(", ")} — check these too before you finish`);
+        }
+        for (const plain of m.alerts)
+            lines.push(`  - ⚠ OPEN ALERT: ${plain}`);
+    }
+    if (modules.length > MAX_MODULES) {
+        lines.push(`- (+${modules.length - MAX_MODULES} more module(s) affected)`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Rutas que ya se avisaron en ESTA sesión y siguen frescas. Sesión distinta →
+ * borrón y cuenta nueva: cada sesión abre con un contexto vacío, así que el
+ * aviso vuelve a hacer falta.
+ */
+export function rutasYaAvisadas(state, sessionId, ahora) {
+    if (!state || state.session_id !== sessionId)
+        return new Set();
+    const vivas = Object.entries(state.seen ?? {}).filter(([, at]) => typeof at === "number" && ahora - at < SEEN_TTL_MS);
+    return new Set(vivas.map(([ruta]) => ruta));
+}
+/** El estado siguiente, podado por TTL y por tamaño (más recientes primero). */
+export function estadoSiguiente(state, sessionId, nuevas, ahora) {
+    const base = state && state.session_id === sessionId ? { ...(state.seen ?? {}) } : {};
+    for (const ruta of nuevas)
+        base[ruta] = ahora;
+    const podado = Object.entries(base)
+        .filter(([, at]) => typeof at === "number" && ahora - at < SEEN_TTL_MS)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, SEEN_MAX);
+    return { session_id: sessionId, seen: Object.fromEntries(podado) };
+}
+/**
+ * Módulos a los que pertenece un archivo, del más reciente al más antiguo.
+ *
+ * UNIÓN de filas y no la última foto, por la misma razón que `moduleFilesUnion`
+ * del guardián: los archivos que toca un módulo cambian en cada análisis, y
+ * quedarse con la fila más nueva silenciaba coincidencias reales (visto en vivo
+ * el 2026-07-18). El riesgo, en cambio, sí es el de la fila más nueva: es
+ * estado, no historia.
+ */
+export function modulosDelArchivo(file, rows) {
+    const out = new Map();
+    for (const row of rows) {
+        const label = (row.module ?? "").trim();
+        if (!label || out.has(label))
+            continue;
+        const files = Array.isArray(row.files) ? row.files.map(String) : [];
+        if (files.includes(file))
+            out.set(label, row.risk);
+    }
+    return [...out.entries()].map(([module, risk]) => ({ module, risk }));
+}
+async function cachePath(dir) {
+    return gitPath(dir, "changebook-impact-cache.json").catch(() => null);
+}
+function leerJson(file) {
+    if (!file)
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function escribirJson(file, data) {
+    if (!file)
+        return;
+    try {
+        fs.writeFileSync(file, JSON.stringify(data));
+    }
+    catch {
+        // Un .git de solo lectura no puede convertirse en una edición fallida.
+    }
+}
+async function fetchAtlas(db, dir, env) {
+    // Mismo proyecto al que reporta analyze/hook: CHANGEBOOK_PROJECT manda, si no
+    // el nombre del directorio, casado por slug del servidor primero.
+    const candidate = env.CHANGEBOOK_PROJECT?.trim() || path.basename(path.resolve(dir));
+    const slug = slugifyProject(candidate);
+    let projects = slug
+        ? await db.rest(`projects?select=id&slug=eq.${encodeURIComponent(slug)}&limit=1`)
+        : [];
+    if (projects.length === 0) {
+        projects = await db.rest(`projects?select=id&name=eq.${encodeURIComponent(candidate)}&limit=1`);
+    }
+    const projectId = projects[0]?.id ?? null;
+    if (!projectId) {
+        return { fetched_at: Date.now(), project_id: null, rows: [], deps: [], alerts: [] };
+    }
+    // TRES consultas en paralelo, una vez cada 5 minutos y fuera del camino
+    // crítico, así que el número de rondas aquí da igual. Lo que NO da igual es
+    // que sean tres y no dos: `deps` y `files` viven en la misma tabla, pero no en
+    // la misma ventana.
+    //
+    // El grafo se pide con `deps=not.is.null`, exactamente como tools.ts. Traerlo
+    // de la ventana general costó un fallo real, cazado en el E2E del 2026-07-26:
+    // de 931 filas recientes solo 613 tenían grafo, así que el mismo módulo salía
+    // con 3 dependientes empujado y 4 preguntado. Dos respuestas para el mismo
+    // hecho, y el agente sin forma de saber cuál le mintió — el fallo contra el
+    // que yo mismo había escrito el comentario de GRAPH_WINDOW_ROWS.
+    //
+    // Y las alertas se traen SIN filtrar por resolved_at, porque las abiertas y la
+    // reincidencia (all-time) salen del mismo conjunto.
+    const [rows, deps, alerts] = await Promise.all([
+        db
+            .rest(`change_module?select=module,files,risk,created_at&project_id=eq.${projectId}&order=created_at.desc&limit=${GRAPH_WINDOW_ROWS}`)
+            .catch(() => []),
+        db
+            .rest(`change_module?select=module,deps&project_id=eq.${projectId}&deps=not.is.null&order=created_at.desc&limit=${GRAPH_WINDOW_ROWS}`)
+            .catch(() => []),
+        db
+            .rest(`regression_alerts?select=module,plain,files,resolved_at,evidence_symbol,evidence_expect&project_id=eq.${projectId}&order=created_at.desc&limit=${ALERT_WINDOW_ROWS}`)
+            .catch(() => []),
+    ]);
+    return { fetched_at: Date.now(), project_id: projectId, rows, deps, alerts };
+}
+/**
+ * Las señales, SIEMPRE de disco. Nunca de la red.
+ *
+ * Esto empezó consultando en línea y no funcionaba, y el fallo enseña más que el
+ * arreglo: medido contra producción el 2026-07-26, resolver el proyecto tarda
+ * ~590 ms y las dos consultas otros ~320 ms. Con el techo por edición no llegaba
+ * — y como no llegaba, nunca escribía la caché, así que TODAS las llamadas eran
+ * en frío para siempre. Una caché que solo se escribe al final de un camino que
+ * no termina no es una caché.
+ *
+ * Así que el camino crítico no toca la red jamás: lee el archivo, y si está frío
+ * o caducado lanza un refresco DESACOPLADO (`impact --warm`) y calla esta vez.
+ * Mismo patrón que el hook post-commit. El coste real es que la primera edición
+ * de cada ventana de 5 minutos no avisa; a cambio, las otras cuarenta cuestan
+ * una lectura de disco. En una sesión de vibe coding ese cambio es todo a favor.
+ */
+async function atlasSignals(db, dir) {
+    const file = await cachePath(dir);
+    // Sin sitio donde guardar (no es un repo git, .git de solo lectura) no hay
+    // canal: calentar sería gastar un proceso y tres consultas para tirar el
+    // resultado a la basura.
+    if (!file)
+        return null;
+    const cached = leerJson(file);
+    if (cached && Date.now() - cached.fetched_at < CACHE_TTL_MS)
+        return cached;
+    if (db.hasCredentials())
+        calentarDesacoplado(dir);
+    return null;
+}
+/**
+ * Lanza el refresco de la caché en un proceso aparte y se olvida de él.
+ *
+ * `stdio: "ignore"` no es higiene, es obligatorio: el stdout del hijo llegaría
+ * a la misma tubería que Claude Code lee como salida del hook, y un JSON a
+ * medias o dos objetos pegados sería basura inyectada en el contexto del agente.
+ * `detached` + `unref` para que el padre pueda morir ya y no retenga la edición.
+ */
+function calentarDesacoplado(dir) {
+    try {
+        const hijo = spawn(process.execPath, [process.argv[1], "impact", "--warm", dir], {
+            detached: true,
+            stdio: "ignore",
+        });
+        hijo.unref();
+    }
+    catch {
+        // Sin poder lanzarlo, la caché se quedará fría y no habrá avisos. Mal, pero
+        // no tan mal como que falle una edición.
+    }
+}
+/**
+ * `changebook impact --warm [dir]` — el lado desacoplado. Consulta y escribe la
+ * caché. Sin stdin, sin stdout, sin código de salida que importe.
+ */
+export async function warmImpactCache(db, dir, env = process.env) {
+    try {
+        if (!db.hasCredentials())
+            return;
+        const file = await cachePath(dir);
+        if (!file)
+            return;
+        // Carrera entre dos ediciones seguidas: si otro proceso ya dejó una caché
+        // fresca mientras este arrancaba, no gastar dos veces la misma consulta.
+        const cached = leerJson(file);
+        if (cached && Date.now() - cached.fetched_at < CACHE_TTL_MS)
+            return;
+        escribirJson(file, await fetchAtlas(db, dir, env));
+    }
+    catch {
+        // Nadie está mirando esta salida; el síntoma de un fallo aquí es que no hay
+        // avisos, y eso ya lo cubre `hook-impact status`.
+    }
+}
+// ── El cuerpo ────────────────────────────────────────────────────────────────
+/** stdin completo, acotado. El hook manda un objeto pequeño; nada más cabe. */
+async function readStdin(limit = 256 * 1024) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of process.stdin) {
+        const buf = Buffer.from(chunk);
+        total += buf.length;
+        if (total > limit)
+            break;
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function buildImpact(db, payload) {
+    const rutas = pathsFromPayload(payload);
+    if (rutas.length === 0)
+        return null;
+    const dir = payload.cwd?.trim() || process.cwd();
+    // El toplevel de git, no el cwd: el agente puede estar en un subdirectorio y
+    // el atlas guarda rutas relativas a la raíz del repo.
+    const toplevel = await execFileAsync("git", ["rev-parse", "--show-toplevel"], {
+        cwd: dir,
+        encoding: "utf8",
+    })
+        .then(({ stdout }) => stdout.trim())
+        .catch(() => dir);
+    const relativas = [
+        ...new Set(rutas
+            .map((r) => repoRelative(toplevel, r))
+            .filter((r) => Boolean(r))),
+    ];
+    if (relativas.length === 0)
+        return null;
+    const ahora = Date.now();
+    const sessionId = payload.session_id?.trim() || "sin-sesion";
+    const seenFile = await gitPath(dir, "changebook-impact-seen.json").catch(() => null);
+    const yaAvisadas = rutasYaAvisadas(leerJson(seenFile), sessionId, ahora);
+    const pendientes = relativas.filter((r) => !yaAvisadas.has(r));
+    if (pendientes.length === 0)
+        return null;
+    const signals = await atlasSignals(db, dir);
+    if (!signals?.project_id)
+        return null;
+    const recidivism = computeRecidivism(signals.alerts);
+    const abiertas = signals.alerts.filter((a) => !a.resolved_at);
+    // Refutación al servir, igual que en atlas_file_context: el mismo grep que
+    // corre el guardián en el pre-commit. De 7 alertas abiertas, 4 se caían con
+    // un grep. Aquí importa el doble: un aviso empujado que ya no es verdad
+    // enseña al agente a ignorar los empujados.
+    //
+    // Acotada a mano, y por una razón que no es cosmética: contarEnRepo usa
+    // execFileSync, o sea que BLOQUEA el bucle de eventos y el techo de arriba no
+    // puede desalojarlo — un Promise.race no gana a una llamada síncrona. Un
+    // archivo con muchas alertas vivas podría comerse el presupuesto entero a
+    // 30 ms por grep. Tres es lo que cabe de sobra; el resto pasa sin refutar,
+    // que es el lado seguro (la duda deja pasar el aviso).
+    let grepsRestantes = MAX_REFUTACIONES;
+    const refutada = (a) => {
+        if (grepsRestantes <= 0)
+            return false;
+        grepsRestantes -= 1;
+        return avisoRefutado(a, (s) => contarEnRepo(toplevel, s));
+    };
+    const depsRows = signals.deps ?? [];
+    const bloques = [];
+    const avisadas = [];
+    for (const file of pendientes) {
+        const modulos = modulosDelArchivo(file, signals.rows);
+        if (modulos.length === 0)
+            continue;
+        const dependientes = dependentsOf(modulos.map((m) => m.module), depsRows);
+        const impactos = modulos
+            .map((m) => ({
+            module: m.module,
+            risk: m.risk,
+            dependents: dependientes.get(m.module) ?? [],
+            alerts: abiertas
+                .filter((a) => (a.module ?? "").trim() === m.module && a.plain)
+                .filter((a) => !refutada(a))
+                .map((a) => a.plain),
+            priorRegressions: recidivism.get(m.module) ?? 0,
+        }))
+            .filter(valeLaPena);
+        if (impactos.length === 0)
+            continue;
+        bloques.push(impactText(file, impactos));
+        avisadas.push(file);
+    }
+    // Solo se marca como avisado lo que de verdad se dijo: si el archivo no tenía
+    // nada hoy pero mañana sale una alerta suya, el aviso tiene que poder salir.
+    if (avisadas.length > 0) {
+        escribirJson(seenFile, estadoSiguiente(leerJson(seenFile), sessionId, avisadas, ahora));
+    }
+    return bloques.length > 0 ? bloques.join("\n\n") : null;
+}
+/**
+ * El comando. Falla abierto SIEMPRE: sin credenciales, sin red, sin proyecto,
+ * con el JSON roto o pasado el presupuesto, se emite cero y se sale con 0.
+ *
+ * Se emite `additionalContext` a secas, sin `permissionDecision`: la decisión de
+ * permisos se queda en manos del usuario, exactamente como si este hook no
+ * existiera. Y por contrato de Claude Code, salir con 2 bloquearía la edición —
+ * de ahí que aquí no se lance nunca nada hacia fuera.
+ */
+export async function printImpact(db) {
+    try {
+        // UN presupuesto para todo, no uno por etapa: dos carreras de 1,2 s en
+        // serie son 2,4 s de impuesto real por edición, que es justo lo que este
+        // techo existe para impedir. Se comparte entre leer stdin y leer la caché.
+        //
+        // Y se cancela en `finally`, no al final del camino feliz: los caminos que
+        // CALLAN son los más frecuentes (archivo limpio, ya avisado, caché fría) y
+        // cada `return` temprano dejaba el temporizador en pie. Medido el
+        // 2026-07-26: 1,39 s por edición silenciosa contra 0,23 s de la que habla —
+        // el proceso ya había terminado y se quedaba esperando a su propio reloj.
+        const { vencido, cancelar } = presupuestoDeTiempo(IMPACT_TIMEOUT_MS);
+        try {
+            const raw = await Promise.race([readStdin(), vencido.then(() => "")]);
+            if (!raw.trim())
+                return;
+            let payload;
+            try {
+                payload = JSON.parse(raw);
+            }
+            catch {
+                return;
+            }
+            const additionalContext = await Promise.race([
+                buildImpact(db, payload).catch(() => null),
+                vencido,
+            ]);
+            if (!additionalContext)
+                return;
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    additionalContext,
+                },
+            }));
+        }
+        finally {
+            cancelar();
+        }
+    }
+    catch {
+        // Editar un archivo no puede fallar por nosotros.
+    }
+}
+//# sourceMappingURL=impact.js.map

package/dist/index.js

@@ -16,11 +16,13 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { analyze } from "./analyze.js";
 import { atlasWebUrl, openInBrowser } from "./browser.js";
 import { clearCredentials, credentialsPath } from "./credentials.js";
+import { recordFeed } from "./feed.js";
 import { runGuard } from "./guard.js";
 import { hookStatus, installHook, uninstallHook } from "./hook.js";
 import { importHistory } from "./import.js";
 import { registerAgents } from "./init.js";
-import { contextHookInstalled, installContextHook, printContext, uninstallContextHook, } from "./context.js";
+import { contextHookInstalled, installContextHook, installSettingsHook, printContext, settingsHookInstalled, uninstallContextHook, uninstallSettingsHook, } from "./context.js";
+import { IMPACT_HOOK, printImpact, warmImpactCache } from "./impact.js";
 import { login } from "./login.js";
 import { AUTH_HELP, Supabase } from "./supabase.js";
 import { syncContextFiles } from "./sync.js";
@@ -51,6 +53,12 @@ Usage:
   changebook hook-context install|uninstall|status [dir]
                           Push the atlas into EVERY Claude Code session at turn 0
                           via a SessionStart hook in .claude/settings.json
+  changebook impact         Print the blast radius of the file a PreToolUse hook
+                          payload (on stdin) is about to edit
+  changebook hook-impact install|uninstall|status [dir]
+                          Tell the agent who depends on a file BEFORE it edits it,
+                          via a PreToolUse hook in .claude/settings.json. Never
+                          blocks an edit; silent when there is nothing to say
   changebook init [dir]     login + register MCP in every agent found + hook + sync
   changebook open           Open the web atlas in the browser
   changebook serve          Run the MCP server on stdio (default with no arguments)
@@ -136,9 +144,36 @@ async function main() {
         }
         case "analyze": {
             const db = new Supabase();
-            requireCredentials(db);
             const options = parseAnalyzeArgs(process.argv.slice(3));
-            await analyze(db, options);
+            const dir = options.dir ?? process.cwd();
+            // --commit IS the post-commit hook's path: the automatic feed, running
+            // detached where nobody reads its output. Record whether it landed so the
+            // next pre-commit can say it out loud (feed.ts). A manual `changebook
+            // analyze` is someone watching the terminal — no pulse needed, and
+            // recording one would let a hand-run failure warn about the hook.
+            const feeding = Boolean(options.commit);
+            if (!db.hasCredentials()) {
+                // Not requireCredentials(): it exits, and being logged out is exactly
+                // the failure the pulse exists to surface.
+                if (feeding)
+                    await recordFeed(dir, { ok: false, reason: "No stored session." });
+                console.error(AUTH_HELP);
+                process.exit(1);
+            }
+            try {
+                await analyze(db, options);
+            }
+            catch (error) {
+                if (feeding) {
+                    await recordFeed(dir, {
+                        ok: false,
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                throw error;
+            }
+            if (feeding)
+                await recordFeed(dir, { ok: true });
             // El mapa de CLAUDE.md/AGENTS.md se regeneraba solo en `init`/`sync`,
             // así que se congelaba el día que lo instalabas (estudio 2026-07-20: la
             // causa nº 1 de que el agente desconfíe del atlas). analyze es el camino
@@ -147,9 +182,7 @@ async function main() {
             // archivos ni resucita un bloque borrado. Best-effort: un sync caído no
             // puede tumbar un análisis ya cobrado y registrado.
             try {
-                await syncContextFiles(db, options.dir ?? process.cwd(), {
-                    refreshOnly: true,
-                });
+                await syncContextFiles(db, dir, { refreshOnly: true });
             }
             catch (error) {
                 console.error(`Map refresh failed (analysis itself succeeded): ${error instanceof Error ? error.message : String(error)}`);
@@ -167,7 +200,14 @@ async function main() {
             // repo must commit exactly as before — runGuard resolves every failure
             // to exit 0 itself. The explicit exit also drops any fetch still racing
             // the timeout, so the commit never waits on a dangling socket.
-            return process.exit(await runGuard(new Supabase(), arg ?? process.cwd()));
+            //
+            // allowRefresh: false — and it is that same exit that makes it necessary.
+            // A dropped fetch is harmless unless it happens to be the token refresh:
+            // Supabase rotates on receipt, so dying mid-flight burns the stored token
+            // without saving its replacement and logs the user out of everything.
+            // The guard is an optional warning with a 3.5s budget; it must never be
+            // able to cost a session. Expired access token → no warning this time.
+            return process.exit(await runGuard(new Supabase(process.env, { allowRefresh: false }), arg ?? process.cwd()));
         }
         case "hook": {
             const dir = process.argv[4] ?? process.cwd();
@@ -213,6 +253,43 @@ async function main() {
             }
             return;
         }
+        case "impact": {
+            // --warm es el lado DESACOPLADO, el que sí toca la red: lo lanza el propio
+            // hook en un proceso aparte cuando encuentra la caché fría. No lee stdin y
+            // no escribe en stdout (ver calentarDesacoplado: su salida iría a la
+            // tubería que Claude Code lee como respuesta del hook).
+            if (arg === "--warm") {
+                await warmImpactCache(new Supabase(), process.argv[4] ?? process.cwd());
+                return;
+            }
+            // Camino crítico de CADA edición: como `context`, jamás requireCredentials
+            // (saldría con 1) y jamás help. printImpact falla abierto — sin sesión,
+            // sin caché o lento, cero salida y exit 0. Y nunca sale con 2, que es el
+            // código con el que Claude Code BLOQUEA la edición.
+            await printImpact(new Supabase());
+            return;
+        }
+        case "hook-impact": {
+            const dir = process.argv[4] ?? process.cwd();
+            if (arg === "install") {
+                const r = installSettingsHook(dir, IMPACT_HOOK);
+                console.error(r === "installed"
+                    ? `✓ PreToolUse hook installed (${dir}/.claude/settings.json). Before every edit, the agent now gets told who depends on the file it is about to touch.`
+                    : "PreToolUse hook already installed.");
+            }
+            else if (arg === "uninstall") {
+                const r = uninstallSettingsHook(dir, IMPACT_HOOK);
+                console.error(r === "removed"
+                    ? "✓ PreToolUse hook removed."
+                    : "No ChangeBook PreToolUse hook found.");
+            }
+            else {
+                console.error(settingsHookInstalled(dir, IMPACT_HOOK)
+                    ? `✓ ChangeBook PreToolUse hook installed (${dir}/.claude/settings.json).`
+                    : "✗ No ChangeBook PreToolUse hook. Install with: changebook hook-impact install");
+            }
+            return;
+        }
         case "init": {
             let db = new Supabase();
             if (!db.hasCredentials()) {
@@ -239,6 +316,15 @@ async function main() {
                 console.error("\nOptional: push the atlas into EVERY Claude Code session at turn 0 " +
                     "(no tool call needed, never stale):\n  changebook hook-context install");
             }
+            // El segundo canal se ofrece aparte porque responde a otra pregunta. El
+            // primero da el mapa al abrir; este avisa de a quién te llevas por delante
+            // justo antes de escribir, que es lo que hace falta cuando nadie pregunta
+            // nada. Se ofrece, NUNCA se instala en silencio: mismo motivo que el otro,
+            // .claude/settings.json se commitea y se comparte.
+            if (!settingsHookInstalled(dir, IMPACT_HOOK)) {
+                console.error("\nOptional: before every edit, tell the agent who depends on the file " +
+                    "it is about to touch:\n  changebook hook-impact install");
+            }
             console.error(`✓ Ready. Ask your agent about the atlas, or open ${atlasWebUrl()}`);
             return;
         }