changebook 0.7.0 → 0.8.0

package/dist/friction.js

@@ -0,0 +1,1016 @@
+/**
+ * `friction.ts` — de dónde sale el mapa de fricción.
+ *
+ * Lee las transcripciones de Claude Code y saca de ellas ediciones ordenadas,
+ * clasifica cada reedición como corrección o continuación, y apila eventos SIN
+ * PROSA para que el drenado los suba.
+ *
+ * Vive aparte de `impact.ts` a propósito: aquél ya son 1.780 líneas.
+ *
+ * Todo lo de este fichero es LOCAL. La prosa que entra aquí no sale de la
+ * máquina; lo que se sube se construye en `eventoDeFriccion`, que es el único
+ * sitio donde se decide qué cruza la frontera.
+ *
+ * Diseño: docs/superpowers/specs/2026-08-23-mapa-de-friccion-design.md
+ */
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { gitPath } from './git.js';
+const TIPOS = new Set([
+    'Edit',
+    'Write',
+    'MultiEdit',
+    'NotebookEdit',
+]);
+/**
+ * ¿Esta línea `user` es un turno de verdad?
+ *
+ * Las líneas `user` que sólo llevan `tool_result` son el eco de una tool, no
+ * algo que dijera el humano. Contarlas rompería el discriminador entero: toda
+ * reedición caería en un "turno" distinto y todo parecería corrección.
+ */
+/** El texto de un turno de usuario, o `null` si esa línea no es un turno. */
+function textoDelTurno(mensaje) {
+    const contenido = mensaje?.content;
+    if (typeof contenido === 'string')
+        return contenido.trim() ? contenido : null;
+    if (!Array.isArray(contenido))
+        return null;
+    const texto = contenido
+        .filter((b) => b?.type === 'text')
+        .map((b) => String(b.text ?? ''))
+        .join(' ');
+    return texto.trim() ? texto : null;
+}
+/**
+ * Turnos que sólo dan permiso para seguir. NO PUEDEN SER UNA CORRECCIÓN.
+ *
+ * MEDIDO el 24/08 etiquetando a mano 20 reediciones que el discriminador de
+ * región llamaba corrección: **15 seguían a un turno así** («hazlo», «ok»,
+ * «sigue») y 3 a boilerplate de herramienta. Sólo 2 seguían a un turno con
+ * contenido. La puntería era del ~10%.
+ *
+ * El mecanismo: el agente construye un fichero A TROZOS y, para añadir lo
+ * siguiente, ancla su `old_string` en lo último que escribió. Eso solapa, y el
+ * solape se leía como «reescribe lo que acababa de escribir». Es el mismo fallo
+ * que el de los ficheros de apilar, que creí resuelto — pero para código.
+ */
+const TURNO_DE_APROBACION = /^\s*(hazlo|haz|ok|okay|vale|sigue|seguimos|continua|continúa|continuamos|dale|perfecto|hecho|listo|si|sí|adelante|bien|genial|gracias|hazlo por m[ií]|\d+)([\s,.!]+(hazlo|todo|ya|por favor|porfa|gracias|continuamos|seguimos|adelante))*\s*[.!,]?\s*$/i;
+/**
+ * Lo que NO lo escribió una persona para este turno.
+ *
+ * MEDIDO el 24/08: de las 23 «correcciones» que sobrevivían a la regla del turno
+ * de aprobación, **6 seguían a un pegote de éstos** —`<system-reminder>`, tres
+ * `<task-notification>`, el aviso de un hook de sesión y un texto de UI pegado—.
+ * Ninguno es alguien pidiendo un arreglo, así que ninguno puede ser el turno que
+ * provocó una corrección.
+ *
+ * Se casa por el PRINCIPIO del turno y con las cadenas exactas del corpus: un
+ * `includes` sobre «task» cazaría cualquier frase que hable de tareas.
+ */
+const TURNO_DE_HERRAMIENTA = new RegExp([
+    '^<[a-z-]+>', // <system-reminder>, <task-notification>, <command-name>…
+    '^\\[(Request|Image)', // interrupciones y adjuntos de imagen
+    '^@"', // fichero adjuntado
+    '^Base directory for this skill',
+    '^A session-scoped Stop hook', // el aviso de /goal
+    '^Connected \\S+@', // el panel de la app, pegado
+    '^\\{"hookSpecificOutput"', // salida cruda de un hook
+].join('|'), 'i');
+/**
+ * ¿Este turno puede haber pedido una corrección?
+ *
+ * Exportada para que el corpus la pruebe por su cuenta: es la mitad del
+ * discriminador que más falsos positivos quita.
+ */
+export function turnoPuedeCorregir(texto) {
+    const t = (texto ?? '').trim();
+    if (!t)
+        return false;
+    return !TURNO_DE_APROBACION.test(t) && !TURNO_DE_HERRAMIENTA.test(t);
+}
+function edicionesDelBloque(bloque, sesion, turno, fecha, turnoTexto) {
+    const nombre = String(bloque.name ?? '');
+    if (!TIPOS.has(nombre))
+        return [];
+    const tipo = nombre;
+    const input = (bloque.input ?? {});
+    const ruta = String(input.file_path ?? input.notebook_path ?? '').trim();
+    if (!ruta)
+        return [];
+    const base = { sesion, turno, ruta, tipo, fecha, turnoTexto };
+    if (tipo === 'MultiEdit') {
+        const edits = Array.isArray(input.edits) ? input.edits : [];
+        return edits
+            .map((e) => e)
+            .filter((e) => typeof e?.new_string === 'string')
+            .map((e) => ({
+            ...base,
+            viejo: typeof e.old_string === 'string' ? e.old_string : null,
+            nuevo: String(e.new_string),
+        }));
+    }
+    if (tipo === 'Write') {
+        return typeof input.content === 'string'
+            ? [{ ...base, viejo: null, nuevo: input.content }]
+            : [];
+    }
+    const nuevo = input.new_string ?? input.new_source;
+    if (typeof nuevo !== 'string')
+        return [];
+    const viejo = input.old_string ?? input.old_source;
+    return [{ ...base, viejo: typeof viejo === 'string' ? viejo : null, nuevo }];
+}
+/**
+ * El texto entero de un `.jsonl` a ediciones ordenadas.
+ *
+ * Toma texto y no una ruta para que el corpus de pruebas se escriba en el propio
+ * test: un detector que sólo se puede probar montando ficheros de verdad acaba
+ * sin corpus.
+ */
+export function edicionesDeTranscripcion(texto) {
+    const ediciones = [];
+    let turnosDeUsuario = 0;
+    let lineasIlegibles = 0;
+    let turnoEnCurso = '';
+    for (const linea of texto.split('\n')) {
+        if (!linea.trim())
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(linea);
+        }
+        catch {
+            lineasIlegibles += 1;
+            continue;
+        }
+        if (obj.type === 'user') {
+            const texto = textoDelTurno(obj.message);
+            if (texto !== null) {
+                turnosDeUsuario += 1;
+                // Recortado: sólo hace falta para decidir si pudo pedir una corrección.
+                turnoEnCurso = texto.replace(/\s+/g, ' ').slice(0, 300);
+            }
+            continue;
+        }
+        if (obj.type !== 'assistant')
+            continue;
+        const contenido = obj.message
+            ?.content;
+        if (!Array.isArray(contenido))
+            continue;
+        const sesion = String(obj.sessionId ?? '');
+        const fecha = String(obj.timestamp ?? '');
+        for (const bloque of contenido) {
+            if (bloque?.type !== 'tool_use')
+                continue;
+            ediciones.push(...edicionesDelBloque(bloque, sesion, turnosDeUsuario, fecha, turnoEnCurso));
+        }
+    }
+    return { ediciones, turnosDeUsuario, lineasIlegibles };
+}
+// ── El discriminador de región ───────────────────────────────────────────────
+//
+// La pregunta que contesta: cuando el agente vuelve a editar un fichero después
+// de que tú hables, ¿está CORRIGIENDO lo que acababa de escribir, o SIGUIENDO
+// con otra cosa? Sin esa distinción, la tasa mide "cuánto se trabaja en este
+// fichero" y no "cuánto sale mal".
+/** Bajo esto, una línea casa entre dos textos cualesquiera. */
+const MIN_CARACTERES_SIGNIFICATIVOS = 8;
+/** Sólo puntuación, cierres o espacios: no identifica nada. */
+const SOLO_PUNTUACION = /^[\s{}()[\];,.:<>/*+\-=|&!?'"`]*$/;
+/**
+ * Las líneas de un texto que sirven para decir "esto es lo mismo que aquello".
+ *
+ * El filtro NO es cosmético: sin él, dos fragmentos cualesquiera de TypeScript
+ * comparten `}` y `  );`, el solape sale siempre cierto y el discriminador se
+ * convierte en un "sí" constante que nadie nota porque parece que funciona.
+ */
+export function lineasSignificativas(texto) {
+    const out = new Set();
+    for (const cruda of texto.split('\n')) {
+        const linea = cruda.trim();
+        if (linea.length < MIN_CARACTERES_SIGNIFICATIVOS)
+            continue;
+        if (SOLO_PUNTUACION.test(linea))
+            continue;
+        out.add(linea);
+    }
+    return out;
+}
+/** ¿Comparten al menos una línea significativa? */
+export function solapan(a, b) {
+    const deA = lineasSignificativas(a);
+    if (deA.size === 0)
+        return false;
+    for (const linea of lineasSignificativas(b)) {
+        if (deA.has(linea))
+            return true;
+    }
+    return false;
+}
+/**
+ * ¿La reedición corrige lo que se acababa de escribir, o sigue con otra cosa?
+ *
+ * Las dos ediciones tienen que ser del mismo fichero; quien llama lo garantiza
+ * agrupando por ruta.
+ */
+export function clasificarReedicion(previa, actual) {
+    // Un Write no tiene texto previo que comparar y reescribe el fichero entero:
+    // por definición se lleva por delante lo que la edición anterior escribió.
+    if (actual.viejo === null)
+        return 'correccion';
+    return solapan(previa.nuevo, actual.viejo) ? 'correccion' : 'continuacion';
+}
+/**
+ * El veredicto de una edición cualquiera, incluida la primera.
+ *
+ * `previa` es la última edición del MISMO fichero en la MISMA sesión, o `null`
+ * si no la hubo. Las reediciones dentro del mismo turno son el agente iterando
+ * solo —1.223 en el corpus del 23/08— y por eso tienen etiqueta propia: cuentan
+ * en el denominador pero no son fricción tuya.
+ */
+export function clasificarEdicion(previa, actual) {
+    if (!previa)
+        return 'primera';
+    if (actual.turno <= previa.turno)
+        return 'iteracion';
+    // Un turno que sólo dice «hazlo» no corrige nada: aprueba. Sin esta guarda el
+    // discriminador tenía ~10% de puntería —15 de 20 «correcciones» etiquetadas a
+    // mano seguían a una aprobación— porque el agente ancla cada trozo nuevo en lo
+    // último que escribió y eso solapa.
+    if (!turnoPuedeCorregir(actual.turnoTexto))
+        return 'continuacion';
+    return clasificarReedicion(previa, actual);
+}
+/**
+ * ¿Esta ruta pertenece al repo?
+ *
+ * El mapa de fricción es DEL REPOSITORIO. En el corpus del 23/08, **481 de las
+ * 2.668 ediciones (18%) caían fuera**: ficheros de memoria del agente en
+ * `~/.claude/projects/.../memory/`, borradores en directorios temporales. Sin
+ * este filtro coronaban el ranking —`MEMORY.md` al 21%— y además su ruta
+ * relativa saldría como `../../...`, que no es un dato válido para subir.
+ *
+ * Es un criterio estructural y no una lista de nombres a propósito: una lista
+ * negra siempre se queda corta contra el fichero que nadie previó.
+ */
+export function dentroDelRepo(ruta, raiz) {
+    const rel = path.relative(raiz, ruta);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+// ── La tasa ──────────────────────────────────────────────────────────────────
+/** Por debajo de esto, un porcentaje es ruido con pinta de dato. */
+export const SUELO_DE_EXPOSICION = 15;
+/**
+ * Correcciones mínimas para decir algo. Una es un suceso, no un patrón.
+ *
+ * Medido el 24/08 tras quitar los falsos positivos del turno de aprobación:
+ * quedan 23 correcciones en TODO el corpus, casi todas sueltas. Publicar por una
+ * sola llenaría el contexto de avisos que no distinguen accidente de costumbre.
+ */
+export const MIN_CORRECCIONES_PARA_HABLAR = 2;
+/**
+ * Las correcciones, UNA A UNA — el encadenado por (sesión, ruta), en un solo
+ * sitio.
+ *
+ * Existe porque hay dos vistas del mismo hecho: la TASA (cuántas sobre cuántas,
+ * para el aviso que se sirve antes de cada edición) y la LISTA (cuáles y
+ * cuándo, para el brief y para `changebook friction`). Medido el 24/08, la
+ * lista es la única que dice algo: 8 correcciones en 30 días no llegan a
+ * ninguna tasa publicable, y sin embargo son 8 hechos concretos con su fecha.
+ *
+ * Sólo cuenta la reedición que CRUZA un turno de usuario. Las del mismo turno
+ * son el agente iterando solo —1.223 de ellas en el corpus del 23/08, contra
+ * 473 que cruzan turno— y medirían su cabezonería, no tu corrección.
+ *
+ * El encadenado es por (sesión, ruta) y no por ruta a secas: dos sesiones a la
+ * vez sobre el mismo fichero producirían "reediciones" cruzadas que son un
+ * artefacto del orden en que se leyeron los ficheros, no un hecho.
+ */
+export function correccionesDeEdiciones(ediciones) {
+    const ultima = new Map();
+    const out = [];
+    for (const e of ediciones) {
+        const clave = `${e.sesion} ${e.ruta}`;
+        const previa = ultima.get(clave);
+        // `clasificarEdicion` y no `clasificarReedicion`: es el MISMO clasificador
+        // que usa `procesarFriccion`. Con dos, el ranking del CLI y lo que se sube
+        // dirían cosas distintas — ya pasó con el módulo, y van tres veces.
+        if (previa &&
+            e.turno > previa.turno &&
+            clasificarEdicion(previa, e) === 'correccion') {
+            out.push(e);
+        }
+        ultima.set(clave, e);
+    }
+    return out;
+}
+/**
+ * De correcciones a filas de fricción, por fichero: la vista de TASA.
+ *
+ * El encadenado no se repite aquí — lo hace `correccionesDeEdiciones`, y este
+ * cuenta lo que aquélla marcó.
+ */
+export function filasDeFriccion(ediciones, opts = {}) {
+    const suelo = opts.sueloDeExposicion ?? SUELO_DE_EXPOSICION;
+    const acc = new Map();
+    // El MISMO encadenado que alimenta la lista de sucesos, por identidad de
+    // objeto. Contar aquí por separado sería la cuarta copia de la regla, y la
+    // tercera ya discrepó.
+    const correcciones = new Set(correccionesDeEdiciones(ediciones));
+    for (const e of ediciones) {
+        const fila = acc.get(e.ruta) ?? {
+            ediciones: 0,
+            correcciones: 0,
+            sesiones: new Set(),
+            conCorreccion: new Set(),
+        };
+        fila.ediciones += 1;
+        fila.sesiones.add(e.sesion);
+        if (correcciones.has(e)) {
+            fila.correcciones += 1;
+            fila.conCorreccion.add(e.sesion);
+        }
+        acc.set(e.ruta, fila);
+    }
+    return [...acc.entries()]
+        .map(([ruta, v]) => ({
+        ruta,
+        ediciones: v.ediciones,
+        correcciones: v.correcciones,
+        sesiones: v.sesiones.size,
+        sesionesConCorreccion: v.conCorreccion.size,
+        // El suelo se compara con las ediciones y no con las correcciones: lo que
+        // hace ruidoso un porcentaje es un denominador pequeño.
+        tasa: v.ediciones >= suelo ? v.correcciones / v.ediciones : null,
+    }))
+        .sort((a, b) => (b.tasa ?? -1) - (a.tasa ?? -1));
+}
+/**
+ * El ÚNICO sitio donde se decide qué sale de la máquina.
+ *
+ * Se construye campo a campo desde una lista blanca, deliberadamente. Un
+ * `{...e}` traería `viejo` y `nuevo` —la prosa, que es lo que este producto
+ * promete no mover— y ningún test que compruebe los campos que espera lo vería.
+ * Por eso el contrato afirma la lista EXACTA de claves: es la única forma de que
+ * un campo de más ponga algo rojo.
+ */
+export function eventoDeFriccion(e, veredicto, modulo, raiz) {
+    return {
+        ruta: path.relative(raiz, e.ruta) || e.ruta,
+        modulo,
+        veredicto,
+        fecha: e.fecha,
+        sesion_hash: createHash('sha256')
+            .update(e.sesion)
+            .digest('hex')
+            .slice(0, 16),
+    };
+}
+// El primer arranque emite el histórico ENTERO de la ventana: 2.187 ediciones
+// dentro del repo en el corpus del 23/08, ~120 bytes cada una. Con el tope de
+// 64 KB de la cola de impacto se recortaría a la mitad en la primera pasada y se
+// perderían eventos justo cuando más hay. 2 MB caben ~16.000.
+const COLA_MAX_BYTES = 2 * 1024 * 1024;
+const COLA_KEEP_BYTES = 1024 * 1024;
+export async function colaDeFriccion(dir) {
+    return gitPath(dir, 'changebook-friction-queue.jsonl').catch(() => null);
+}
+/**
+ * Apila un evento. JSONL y no JSON, por lo mismo que la cola de impacto: un
+ * append no lee lo que ya hay y dos procesos solapados no se pisan.
+ *
+ * Best-effort de principio a fin: registrar la fricción no puede tumbar el
+ * calentamiento que la provocó.
+ */
+export function encolarFriccion(file, evento) {
+    if (!file)
+        return;
+    try {
+        try {
+            if (fs.statSync(file).size > COLA_MAX_BYTES) {
+                fs.writeFileSync(file, fs.readFileSync(file).subarray(-COLA_KEEP_BYTES));
+            }
+        }
+        catch {
+            // Aún no existe: nada que recortar.
+        }
+        fs.appendFileSync(file, `${JSON.stringify(evento)}\n`);
+    }
+    catch {
+        // Sin sitio donde anotar, el resto del warm sigue igual.
+    }
+}
+/**
+ * Órdenes de shell que casi seguro escriben en un fichero del repo.
+ *
+ * Deliberadamente conservador: prefiere no contar una escritura real a inflar el
+ * punto ciego con `grep` y `ls`. El número es una cota INFERIOR y se dice así.
+ */
+const SHELL_QUE_ESCRIBE = /(^|[\s;&|])(sed\s+-i|tee\s|cat\s*>|python3?\s+-[cm]\b|>>?\s*\S+\.(?:ts|tsx|js|mjs|sql|md|json|yml|yaml))/;
+/**
+ * Sin el corchete de cierre: la variante `for tool use` fue 3 de las 17 medidas
+ * el 23/08, y anclar a `]` se las come sin que nada se ponga rojo.
+ */
+const INTERRUPCION = '[Request interrupted by user';
+/**
+ * La frase ENTERA, no las palabras sueltas. `permission`, `denied` o `rejected`
+ * por separado casan con código fuente de este mismo repo, y con la denegación
+ * del clasificador de auto mode —25 en el corpus— que NO es un rechazo tuyo.
+ */
+const RECHAZO = "The user doesn't want to proceed with this tool use";
+/**
+ * Los actos inequívocos: 20 en las 31 sesiones medidas el 23/08.
+ *
+ * Escasos a propósito. Su valor no es medir fricción —para eso no llegan— sino
+ * poder contrastarlos con la tasa: si esto marca y la tasa no, el discriminador
+ * está roto. Es la mitad del Invariante 17 que permite distinguir «este repo no
+ * tiene fricción» de «el instrumento se murió».
+ *
+ * NUNCA se suman a la tasa: un escalar mezclado no se puede validar contra un
+ * corpus y esconde cuál de las dos mitades falló.
+ */
+export function actosExplicitos(texto) {
+    let interrupciones = 0;
+    let rechazos = 0;
+    let edicionesPorShell = 0;
+    const rutasDeShell = new Set();
+    for (const linea of texto.split('\n')) {
+        if (!linea.trim())
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(linea);
+        }
+        catch {
+            continue; // Las ilegibles ya las cuenta `edicionesDeTranscripcion`.
+        }
+        const contenido = obj.message
+            ?.content;
+        if (!Array.isArray(contenido))
+            continue;
+        for (const b of contenido) {
+            const bloque = b;
+            if (bloque.type === 'text' &&
+                typeof bloque.text === 'string' &&
+                bloque.text.includes(INTERRUPCION)) {
+                interrupciones += 1;
+            }
+            if (bloque.type === 'tool_result') {
+                const txt = typeof bloque.content === 'string'
+                    ? bloque.content
+                    : JSON.stringify(bloque.content ?? '');
+                if (txt.includes(RECHAZO))
+                    rechazos += 1;
+            }
+            const conTool = bloque;
+            if (bloque.type === 'tool_use' &&
+                conTool.name === 'Bash' &&
+                typeof conTool.input?.command === 'string' &&
+                SHELL_QUE_ESCRIBE.test(conTool.input.command)) {
+                edicionesPorShell += 1;
+                for (const r of rutasEscritasPorShell(conTool.input.command))
+                    rutasDeShell.add(r);
+            }
+        }
+    }
+    return {
+        interrupciones,
+        rechazos,
+        edicionesPorShell,
+        rutasDeShell: [...rutasDeShell],
+    };
+}
+// ── La pasada: marca de agua, ventana y vitalidad ────────────────────────────
+export const VENTANA_DIAS = 30;
+/** Menos turnos que esto y no cabe el patrón «editó, hablaste, reeditó». */
+export const MIN_TURNOS_DE_USUARIO = 3;
+/**
+ * La marca del primer arranque.
+ *
+ * Los desplazamientos arrancan VACÍOS, o sea en cero, y NO al final de cada
+ * fichero. Poner la marca al final tiraría toda la historia previa —321 MB en
+ * este repo— y el mapa nacería vacío el día de la instalación. Lo viejo lo
+ * descarta la ventana, por FECHA, no por posición; así el histórico recorre el
+ * mismo camino que lo vivo y no hay una segunda implementación que pueda
+ * divergir (Invariante 15).
+ */
+export function marcaInicial(ahoraMs, _ventanaDias = VENTANA_DIAS) {
+    return {
+        porFichero: {},
+        ultimaLecturaMs: ahoraMs,
+        bytesLeidos: 0,
+        sesionesVistas: 0,
+        eventos: 0,
+        lineasIlegibles: 0,
+        bordesDeLectura: 0,
+        sesionesFinas: 0,
+        fueraDelRepo: 0,
+        interrupciones: 0,
+        rechazos: 0,
+        edicionesPorShell: 0,
+        ultimoErrorDeSubida: null,
+    };
+}
+export async function marcaPath(dir) {
+    return gitPath(dir, 'changebook-friction-state.json').catch(() => null);
+}
+function leerMarca(file, ahoraMs) {
+    if (!file)
+        return marcaInicial(ahoraMs);
+    try {
+        const previa = JSON.parse(fs.readFileSync(file, 'utf8'));
+        // El formato viejo guardaba un número suelto por fichero. Se migra al leer
+        // en vez de tirarlo: tirarlo releería 274 MB y duplicaría todos los eventos.
+        const porFichero = {};
+        for (const [k, v] of Object.entries(previa.porFichero ?? {})) {
+            porFichero[k] = typeof v === 'number' ? { bytes: v, turnos: 0 } : v;
+        }
+        return { ...marcaInicial(ahoraMs), ...previa, porFichero };
+    }
+    catch {
+        return marcaInicial(ahoraMs);
+    }
+}
+/**
+ * El directorio donde Claude Code guarda las transcripciones de este repo.
+ *
+ * El nombre es la ruta absoluta con las barras y los puntos sustituidos por
+ * guiones, que es la convención de Claude Code. Se deriva, no se adivina.
+ */
+export function dirDeTranscripciones(dir, home = process.env.HOME ?? '') {
+    return path.join(home, '.claude', 'projects', path.resolve(dir).replace(/[/.]/g, '-'));
+}
+/**
+ * Una pasada: lee lo nuevo de cada transcripción, clasifica y encola.
+ *
+ * Devuelve la marca resultante para que quien llama pueda enseñarla; los
+ * contadores son el canal de vitalidad, no adorno.
+ */
+export async function procesarFriccion(dir, deps) {
+    const file = await marcaPath(dir);
+    const marca = leerMarca(file, deps.ahoraMs);
+    const cola = await colaDeFriccion(dir);
+    const pendientesDeShell = [];
+    const limite = deps.ahoraMs - VENTANA_DIAS * 24 * 60 * 60 * 1000;
+    let nombres;
+    try {
+        nombres = fs
+            .readdirSync(deps.dirTranscripciones)
+            .filter((n) => n.endsWith('.jsonl'));
+    }
+    catch {
+        return marca; // Sin directorio de transcripciones no hay nada que leer.
+    }
+    for (const nombre of nombres) {
+        const ruta = path.join(deps.dirTranscripciones, nombre);
+        let tamano;
+        try {
+            tamano = fs.statSync(ruta).size;
+        }
+        catch {
+            continue;
+        }
+        const estado = marca.porFichero[nombre] ?? { bytes: 0, turnos: 0 };
+        let desde = estado.bytes;
+        // Rotación o truncado: la marca apunta más allá del final. Volver a cero en
+        // vez de leer basura o callar.
+        if (desde > tamano)
+            desde = 0;
+        if (desde === tamano)
+            continue;
+        let texto;
+        try {
+            const fd = fs.openSync(ruta, 'r');
+            try {
+                const buf = Buffer.alloc(tamano - desde);
+                fs.readSync(fd, buf, 0, buf.length, desde);
+                texto = buf.toString('utf8');
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            continue;
+        }
+        marca.bytesLeidos += texto.length;
+        const actos = actosExplicitos(texto);
+        marca.interrupciones += actos.interrupciones;
+        marca.rechazos += actos.rechazos;
+        marca.edicionesPorShell += actos.edicionesPorShell;
+        // Para que el hook las vea en su próximo disparo. Aquí, y no en un hook de
+        // `Bash`: esto ya corre desacoplado y no cuesta latencia a nadie.
+        pendientesDeShell.push(...actos.rutasDeShell);
+        const lectura = edicionesDeTranscripcion(texto);
+        marca.lineasIlegibles += lectura.lineasIlegibles;
+        // Turnos de la SESIÓN, no del trozo. El desplazamiento se guarda aunque la
+        // sesión se salte por fina: si no, nunca dejaría de serlo.
+        const turnosPrevios = estado.turnos;
+        const turnosTotales = turnosPrevios + lectura.turnosDeUsuario;
+        marca.porFichero[nombre] = { bytes: tamano, turnos: turnosTotales };
+        if (turnosTotales < MIN_TURNOS_DE_USUARIO) {
+            marca.sesionesFinas += 1;
+            continue;
+        }
+        marca.sesionesVistas += 1;
+        const ultima = new Map();
+        for (const cruda of lectura.ediciones) {
+            // El índice de turno viene relativo al TROZO; se corre para que sea de la
+            // sesión. Sin esto, dos trozos de la misma sesión tendrían turnos 1,2,3 y
+            // 1,2,3 otra vez.
+            const e = { ...cruda, turno: cruda.turno + turnosPrevios };
+            // El mapa es DEL REPO: 18% de las ediciones del corpus caen fuera.
+            if (!dentroDelRepo(e.ruta, dir)) {
+                marca.fueraDelRepo += 1;
+                continue;
+            }
+            if (Date.parse(e.fecha) < limite)
+                continue;
+            const clave = `${e.sesion} ${e.ruta}`;
+            const previa = ultima.get(clave) ?? null;
+            // La pérdida conocida de leer por trozos: la edición anterior a ésta pudo
+            // quedar en el trozo previo, y entonces se clasifica `primera` en vez de
+            // compararse. Se cuenta; sesga a la baja, nunca al alza.
+            if (!previa && turnosPrevios > 0)
+                marca.bordesDeLectura += 1;
+            // Se emite UNA fila por edición, no sólo por reedición: sin las `primera`
+            // y las `iteracion` el servidor no tendría denominador y publicaría una
+            // tasa distinta a la del CLI bajo el mismo nombre.
+            encolarFriccion(cola, eventoDeFriccion(e, clasificarEdicion(previa, e), deps.moduloDe(e.ruta), dir));
+            marca.eventos += 1;
+            ultima.set(clave, e);
+        }
+    }
+    anotarPendientesDeShell(await pendientesDeShellPath(dir), pendientesDeShell);
+    marca.ultimaLecturaMs = deps.ahoraMs;
+    if (file) {
+        try {
+            fs.writeFileSync(file, `${JSON.stringify(marca, null, 2)}\n`);
+        }
+        catch {
+            // Sin marca persistida se relee la próxima vez: se repite trabajo, no se pierde.
+        }
+    }
+    return marca;
+}
+/**
+ * El canal de vitalidad (Invariante 17).
+ *
+ * La pregunta que contesta no es «¿cuánta fricción hay?» sino «¿sigo vivo?».
+ * Un repo tranquilo y un lector roto producen el mismo cero, y sin esta función
+ * no habría forma de distinguirlos.
+ */
+export function diagnosticoDeFriccion(marca, edicionesDelRepo) {
+    const lineas = edicionesDelRepo > 0 && marca.bytesLeidos === 0
+        ? [
+            'Lector de fricción: MUERTO.',
+            `El repo registró ${edicionesDelRepo} ediciones y el lector leyó 0 bytes de transcripción.`,
+            'Eso no es un repo tranquilo: es que no está leyendo.',
+            'Comprueba que ~/.claude/projects tiene el directorio de este repo.',
+        ]
+        : [
+            'Lector de fricción: vivo.',
+            `Bytes leídos: ${marca.bytesLeidos}. Sesiones: ${marca.sesionesVistas}. Eventos: ${marca.eventos}.`,
+            `Descartes: ${marca.sesionesFinas} sesiones finas, ${marca.fueraDelRepo} ediciones fuera del repo, ${marca.lineasIlegibles} líneas ilegibles.`,
+        ];
+    // Los actos explícitos van en línea propia y NUNCA sumados a la tasa: son el
+    // canal limpio, y su utilidad es poder contrastarlo con el denso.
+    lineas.push(`Actos explícitos (aparte de la tasa): ${marca.interrupciones} interrupciones, ${marca.rechazos} rechazos.`);
+    // El punto ciego, dicho en voz alta. Sin esto, un fichero que se edita siempre
+    // por shell sale con fricción baja y se lee igual que uno que va bien.
+    if (marca.edicionesPorShell > 0) {
+        lineas.push(`⚠ Punto ciego: al menos ${marca.edicionesPorShell} escrituras por shell (sed, heredoc) que la fricción NO puede ver.`);
+    }
+    // El fallo de subida se dice en LAS DOS ramas, y por eso esto va fuera del
+    // if/else. Leer y no poder subir son hechos independientes: la primera versión
+    // salía por `return` en la rama MUERTO y se callaba el 403 justo en el caso más
+    // común —estado recién creado, cero bytes leídos esta pasada—. Lo cazó su test.
+    if (marca.ultimoErrorDeSubida) {
+        lineas.push(`⚠ La última subida FALLÓ: ${marca.ultimoErrorDeSubida}`, '  La cola local sigue entera y se reintenta en la próxima pasada.');
+    }
+    return lineas.join('\n');
+}
+/** La marca guardada, para el diagnóstico y para los tests. */
+export async function estadoDeFriccion(dir) {
+    return leerMarca(await marcaPath(dir), Date.now());
+}
+/** Anota en la marca cómo fue la última subida. Best-effort. */
+async function anotarSubida(dir, error) {
+    const file = await marcaPath(dir);
+    if (!file)
+        return;
+    try {
+        const marca = leerMarca(file, Date.now());
+        marca.ultimoErrorDeSubida = error;
+        fs.writeFileSync(file, `${JSON.stringify(marca, null, 2)}\n`);
+    }
+    catch {
+        // Si no se puede anotar, el drenado ya hizo lo importante: no perder la cola.
+    }
+}
+/**
+ * Vacía la cola de fricción contra `friction_event`.
+ *
+ * Corre en `impact --warm`, en la misma pasada que ya vacía `atlas_reads` y que
+ * ya paga red.
+ *
+ * NO LANZA, y esa es la decisión de diseño: `insertRow` sí lanza, y esto corre
+ * dentro del `try/catch` de `warmImpactCache`, que se lo tragaría. Un 403 por
+ * una policy mal puesta se leería EXACTAMENTE igual que «no había nada que
+ * subir». Así que el fallo se captura aquí, la cola **no se vacía** —nada se
+ * pierde, se reintenta— y queda anotado en la marca para que el diagnóstico
+ * pueda decirlo en voz alta.
+ */
+export async function drenarFriccion(db, dir, projectId) {
+    const file = await colaDeFriccion(dir);
+    if (!file)
+        return { subidos: 0, ilegibles: 0, error: null };
+    let contenido;
+    try {
+        contenido = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return { subidos: 0, ilegibles: 0, error: null }; // No hay cola: el caso normal.
+    }
+    const eventos = [];
+    let ilegibles = 0;
+    for (const linea of contenido.split('\n')) {
+        if (!linea.trim())
+            continue;
+        try {
+            eventos.push(JSON.parse(linea));
+        }
+        catch {
+            // Línea partida por el recorte de la cola: se tira sola, pero se cuenta.
+            ilegibles += 1;
+        }
+    }
+    let subidos = 0;
+    for (const e of eventos) {
+        try {
+            // La fila se construye campo a campo, igual que el evento: `user_id` lo
+            // pone el default `auth.uid()` del esquema, así que NO viaja aquí.
+            await db.insertRow('friction_event', {
+                project_id: projectId,
+                path: e.ruta,
+                module: e.modulo,
+                veredicto: e.veredicto,
+                occurred_at: e.fecha,
+                session_hash: e.sesion_hash,
+            });
+            subidos += 1;
+        }
+        catch (err) {
+            const error = (err instanceof Error ? err.message : String(err)).slice(0, 200);
+            // La cola se queda ENTERA a propósito. Reintentar y duplicar es peor que
+            // perder, pero perder en silencio es lo peor de los tres.
+            await anotarSubida(dir, error);
+            return { subidos, ilegibles, error };
+        }
+    }
+    // Sólo se borra DESPUÉS de subirlo todo.
+    try {
+        fs.writeFileSync(file, '');
+    }
+    catch {
+        // Se reintenta en la próxima pasada: duplicará, no perderá.
+    }
+    await anotarSubida(dir, null);
+    return { subidos, ilegibles, error: null };
+}
+// ── La entrega al agente ─────────────────────────────────────────────────────
+/**
+ * De filas de `friction_event` a una `FilaDeFriccion`.
+ *
+ * El denominador son TODAS las filas, no sólo las correcciones, y por eso la
+ * tabla guarda los cuatro veredictos. Si guardara sólo las reediciones, esta
+ * función y `filasDeFriccion` —la del CLI, que cuenta sobre las ediciones de la
+ * transcripción— publicarían números distintos con el mismo nombre.
+ */
+export function filaDesdeEventos(ruta, eventos, opts = {}) {
+    const suelo = opts.sueloDeExposicion ?? SUELO_DE_EXPOSICION;
+    const sesiones = new Set();
+    const conCorreccion = new Set();
+    let correcciones = 0;
+    for (const e of eventos) {
+        sesiones.add(e.session_hash);
+        if (e.veredicto === 'correccion') {
+            correcciones += 1;
+            conCorreccion.add(e.session_hash);
+        }
+    }
+    return {
+        ruta,
+        ediciones: eventos.length,
+        correcciones,
+        sesiones: sesiones.size,
+        sesionesConCorreccion: conCorreccion.size,
+        // Truncado ⇒ sin tasa. El conteo de correcciones sigue siendo cierto («vi
+        // al menos N»), pero el porcentaje sería sobre un denominador cortado.
+        tasa: !opts.truncado && eventos.length >= suelo
+            ? correcciones / eventos.length
+            : null,
+        ...(opts.truncado ? { truncado: true } : {}),
+    };
+}
+/**
+ * La línea que ve el agente. `null` cuando no hay nada que decir.
+ *
+ * Acepta `undefined` a propósito: quien la llama suele venir de un `Map.get`,
+ * y una guarda por cada sitio de llamada es una guarda que algún día falta.
+ *
+ * Callar sin correcciones es deliberado: esta línea se inyecta ANTES de cada
+ * edición, y un «Fricción: 0%» en todas entrena a ignorar el bloque entero —y
+ * entonces deja de servir el aviso que sí importa.
+ */
+export function lineaDeFriccion(fila) {
+    // DOS correcciones como mínimo para decir nada. Una es un suceso, no un
+    // patrón, y esta línea se sirve ANTES DE CADA EDICIÓN de ese fichero: un aviso
+    // que no distingue accidente de costumbre entrena a ignorar el bloque entero,
+    // y entonces deja de servir el que sí importa.
+    if (!fila || fila.correcciones < MIN_CORRECCIONES_PARA_HABLAR)
+        return null;
+    if (fila.truncado) {
+        return `Fricción: al menos ${fila.correcciones} correcciones (el servidor cortó el histórico; sin tasa fiable).`;
+    }
+    if (fila.tasa === null) {
+        return `Fricción: ${fila.correcciones} correcciones en ${fila.ediciones} ediciones (pocas para una tasa).`;
+    }
+    const pct = Math.round(fila.tasa * 100);
+    return `Fricción: ${pct}% — ${fila.correcciones} de ${fila.ediciones} ediciones, en ${fila.sesionesConCorreccion} de ${fila.sesiones} sesiones (últimos ${VENTANA_DIAS} días).`;
+}
+/**
+ * Un suceso en una línea.
+ *
+ * La fecha se RECORTA de la cadena ISO en vez de parsearse: `new Date(iso)` y
+ * luego `getDate()` devuelve el día en la zona horaria de quien mire, así que
+ * un suceso de las 00:30 UTC se publicaría con el día anterior para media
+ * Europa y con el correcto para la otra media. `occurred_at` es UTC y el
+ * recorte lo mantiene UTC.
+ */
+export function lineaDeSuceso(s) {
+    // Acepta una fecha ausente por el mismo motivo por el que `lineaDeFriccion`
+    // acepta `undefined`: una guarda por cada sitio de llamada es una guarda que
+    // algún día falta. `occurred_at` es `not null` en la tabla, pero esta función
+    // es pura y la llama quien quiera con las filas que quiera.
+    const dia = /^(\d{4})-(\d{2})-(\d{2})/.exec(s.fecha ?? '');
+    const cuando = dia ? `${dia[3]}/${dia[2]}` : (s.fecha ?? 'sin fecha');
+    return s.modulo
+        ? `${cuando} · ${s.ruta} — ${s.modulo}`
+        : `${cuando} · ${s.ruta}`;
+}
+/**
+ * El ranking local, para `changebook friction`.
+ *
+ * Relee las transcripciones enteras en vez de partir de la marca de agua: la
+ * marca sirve para no reprocesar en el camino caliente, pero esta orden se
+ * invoca a mano y tiene que contestar aunque el `--warm` ya haya drenado la
+ * cola. Si algún día molesta el coste, el arreglo es guardar agregados, no
+ * acelerar la lectura.
+ */
+export function rankingDeFriccion(dir, home, tope = 10, ahoraMs = Date.now()) {
+    // LA MISMA VENTANA que `procesarFriccion`. Sin esto el ranking se calculaba
+    // sobre TODA la historia mientras su propia línea decía «últimos 30 días»: la
+    // etiqueta mentía, y mentía hacia arriba porque el numerador crecía sin tope.
+    const limite = ahoraMs - VENTANA_DIAS * 24 * 60 * 60 * 1000;
+    const dirT = dirDeTranscripciones(dir, home);
+    let nombres;
+    try {
+        nombres = fs.readdirSync(dirT).filter((n) => n.endsWith('.jsonl'));
+    }
+    catch {
+        return `Sin transcripciones en ${dirT}.`;
+    }
+    const ediciones = [];
+    for (const nombre of nombres) {
+        let texto;
+        try {
+            texto = fs.readFileSync(path.join(dirT, nombre), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const lectura = edicionesDeTranscripcion(texto);
+        if (lectura.turnosDeUsuario < MIN_TURNOS_DE_USUARIO)
+            continue;
+        // Mismo filtro que la pasada: el mapa es DEL REPO.
+        ediciones.push(...lectura.ediciones.filter((e) => dentroDelRepo(e.ruta, dir) && Date.parse(e.fecha) >= limite));
+    }
+    const sucesos = correccionesDeEdiciones(ediciones)
+        .map((e) => ({
+        fecha: e.fecha,
+        ruta: path.relative(dir, e.ruta),
+        modulo: null,
+    }))
+        .sort((a, b) => (b.fecha ?? '').localeCompare(a.fecha ?? ''));
+    // VACÍO ES UN DATO, y se dice. Un «no hay nada» a secas se lee igual que un
+    // instrumento averiado —Invariante 17—, y aquí el caso normal es el vacío:
+    // medido el 24/08, 8 correcciones en 30 días.
+    if (sucesos.length === 0) {
+        return (`Sin correcciones en los últimos ${VENTANA_DIAS} días.\n` +
+            `(Vacío significa que no has tenido que rehacer trabajo del agente. ` +
+            `Si el lector estuviera parado lo diría el diagnóstico de aquí arriba.)`);
+    }
+    const mostrados = sucesos.slice(0, tope);
+    const lineas = [
+        `${sucesos.length} ${sucesos.length === 1 ? 'corrección' : 'correcciones'} en los últimos ${VENTANA_DIAS} días:`,
+        ...mostrados.map((x) => `  ${lineaDeSuceso(x)}`),
+    ];
+    // Sin esto, un tope alcanzado se lee como «esto es todo». Es la regla de no
+    // recortar en silencio, y ya costó una medición este mes.
+    if (sucesos.length > mostrados.length) {
+        lineas.push(`  … y ${sucesos.length - mostrados.length} más (sube el tope para verlas).`);
+    }
+    return lineas.join('\n');
+}
+// ── El punto ciego del shell, cerrado por el canal desacoplado ───────────────
+//
+// MEDIDO el 24/08 sobre 30 sesiones reales: de 153 pares (sesión, módulo)
+// tocados por shell, **30 eran módulos que ninguna edición por tool avisó**, y
+// ~19 de ésos SÍ valían un aviso —`Publicación` (4 dependientes, 3
+// reincidencias), `Búsqueda de símbolos` (4 y 2), `Integración de MCP` (3 y 2)—.
+// Un aviso perdido por sesión, y de los caros.
+//
+// Se resuelve AQUÍ y no enganchando `Bash` al `PreToolUse`: este código ya corre
+// desacoplado dentro de `impact --warm`. Poner un hook en cada llamada a Bash
+// pagaría latencia en el camino más frecuente que hay.
+/**
+ * Las rutas que un comando de shell escribe, de las formas que se pueden leer
+ * **sin adivinar**.
+ *
+ * Deliberadamente corto: `sed -i`, las redirecciones y `tee`. No intenta
+ * `python -c` ni un heredoc con la ruta en una variable — un extractor que
+ * inventa rutas es peor que uno que se queda corto, porque avisa del fichero
+ * equivocado. El resultado es una COTA INFERIOR y se dice así.
+ */
+export function rutasEscritasPorShell(cmd) {
+    // ANCLADA AL FINAL con `(?![\\w.])`, y no es cosmético: la alternancia de una
+    // regex gana con el PRIMERO que casa, así que `js` se llevaba `salida.json` y
+    // devolvía `salida.js` —un fichero que no existe—. Un extractor que inventa
+    // rutas avisa del fichero equivocado, que es peor que quedarse corto.
+    // Cazado por su propio test el 24/08.
+    const EXT = '(?:tsx|ts|mjs|cjs|js|sql|md|json|yaml|yml|css|html)(?![\\w.])';
+    const out = new Set();
+    const add = (re) => {
+        for (const m of cmd.matchAll(re))
+            if (m[1])
+                out.add(m[1]);
+    };
+    // Redirección: `> a.ts`, `>> a.ts`. No casa `2>/dev/null` porque exige extensión.
+    add(new RegExp(`>>?\\s*([^\\s;&|<>"']+\\.${EXT})`, 'g'));
+    // `sed -i` (con o sin el '' de BSD), con la ruta al final.
+    add(new RegExp(`sed\\s+-i\\b[^;&|]*?([^\\s;&|'"]+\\.${EXT})`, 'g'));
+    add(new RegExp(`tee\\s+(?:-a\\s+)?([^\\s;&|]+\\.${EXT})`, 'g'));
+    return [...out];
+}
+/** Fichero donde se apuntan las rutas de shell pendientes de avisar. */
+export async function pendientesDeShellPath(dir) {
+    return gitPath(dir, 'changebook-impact-shell.json').catch(() => null);
+}
+/**
+ * Apunta las rutas escritas por shell para que el hook las vea en su próximo
+ * disparo. Best-effort: no poder anotarlas no puede tumbar el warm.
+ */
+export function anotarPendientesDeShell(file, rutas) {
+    if (!file || rutas.length === 0)
+        return;
+    try {
+        let previas = [];
+        try {
+            const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (Array.isArray(j.rutas))
+                previas = j.rutas.filter((x) => typeof x === 'string');
+        }
+        catch {
+            // Aún no existe o está roto: se empieza de cero.
+        }
+        // Tope para que una tanda enorme no haga crecer el fichero sin freno; se
+        // quedan las MÁS RECIENTES, que son las que el aviso todavía puede alcanzar.
+        const todas = [...new Set([...previas, ...rutas])].slice(-40);
+        fs.writeFileSync(file, `${JSON.stringify({ rutas: todas }, null, 2)}\n`);
+    }
+    catch {
+        // Ver arriba.
+    }
+}
+/** Las lee y las BORRA: un aviso pendiente se sirve una vez. */
+export function tomarPendientesDeShell(file) {
+    if (!file)
+        return [];
+    try {
+        const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const rutas = Array.isArray(j.rutas)
+            ? j.rutas.filter((x) => typeof x === 'string')
+            : [];
+        if (rutas.length > 0)
+            fs.writeFileSync(file, `{"rutas":[]}\n`);
+        return rutas;
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=friction.js.map