changebook 0.4.7 → 0.4.9

package/README.md

@@ -2,10 +2,10 @@
 
 MCP (Model Context Protocol) server that lets coding agents — Claude Code,
 Codex, Cursor — query the **ChangeBook product memory** (the module map and the
-analyzed change history stored in Supabase) instead of re-reading the
-codebase, plus a CLI that feeds that memory from any terminal: sign in,
+analyzed change history from your ChangeBook account) instead of re-reading
+the codebase, plus a CLI that feeds that memory from any terminal: sign in,
 analyze uncommitted changes, sync the product map. All MCP tools are
-read-only, and Row Level Security scopes every query to the signed-in user.
+read-only, and every query is scoped to the signed-in user.
 
 ## Two ways to run it
 
@@ -50,6 +50,9 @@ your other servers.
 | `changebook analyze [dir]` | Analyze the repo's uncommitted changes (`git diff HEAD`) and update the atlas — same pipeline as the VS Code extension, no editor needed. |
 | `changebook analyze --commit [ref]` | Analyze one commit. Deduped by hash server-side, so re-runs never bill. |
 | `changebook hook install\|uninstall\|status [dir]` | Git hooks: every new commit is analyzed in the background (post-commit, never blocks), and the signal guard warns before you commit to a module with an open alert (pre-commit). One pair of hooks covers Claude Code, Codex and manual commits — they all commit through git. |
+| `changebook hook-context install\|uninstall\|status [dir]` | Claude Code `SessionStart` hook: pushes the fresh atlas map into **every** session at turn 0 — no tool call to remember, and generated on the spot so it can't go stale. Writes to `.claude/settings.json`; running the command **is** the consent, and it refuses to touch a config it can't parse. |
+| `changebook hook-impact install\|uninstall\|status [dir]` | Claude Code `PreToolUse` hook: **before every edit**, tells the agent which modules depend on the file it is about to touch, plus any open alert and repeat-offender history. Never blocks an edit, never touches the network on the critical path (reads a short-lived cache in `.git/` and refreshes it out of band), warns once per file per session, and stays **silent** when there is nothing to say. |
+| `changebook impact` / `changebook context [dir]` | What those two hooks run. Both read from stdin/disk, print a JSON payload (or nothing) and always exit 0 — you don't call them by hand. |
 | `changebook guard [dir]` | What the pre-commit hook runs: checks staged files against the atlas' open alerts. Warn-only and fail-open by default; `CHANGEBOOK_GUARD=block` makes findings abort the commit (bypass once with `git commit --no-verify`), `CHANGEBOOK_GUARD=off` silences it. |
 | `changebook sync [dir]` | Refresh the product map inside `CLAUDE.md`/`AGENTS.md`. |
 | `changebook init [dir]` | login + register MCP server + install hook + sync, in one go. |
@@ -96,11 +99,6 @@ env vars below override them for CI/headless setups.
 | `CHANGEBOOK_ACCESS_TOKEN` | — | Short-lived JWT; refreshed automatically when it expires. |
 | `CHANGEBOOK_PROJECT` | — | Scope every query to one project (matched by slug, then exact name — usually the workspace folder name). Unset = all projects. |
 | `CHANGEBOOK_WEB_URL` | `https://changebook.app` | Web app used by `login`/`open` and printed after `analyze`. |
-| `CHANGEBOOK_SUPABASE_URL` | production project | Override for other environments. |
-| `CHANGEBOOK_SUPABASE_ANON_KEY` | production public key | Override for other environments. |
-
-The embedded anon key is the same public key the web app ships — it grants
-nothing by itself; your session token plus RLS decide what you can read.
 
 ## `sync`: product map inside CLAUDE.md / AGENTS.md
 
@@ -119,7 +117,7 @@ touched. Re-run after analyzing changes (or wire it to a git hook).
 ## Security notes
 
 - MCP tools are read-only; only `analyze` writes (through the same audited
-  Edge Function as the extension, with the same quotas).
+  server endpoint as the extension, with the same quotas).
 - `login` uses a loopback-only handoff: the web app asks for an explicit
   Authorize click and redirects the tokens to `http://127.0.0.1:<port>` in
   the URL fragment — they never leave your machine, and a `state` nonce ties

package/dist/analyze.js

@@ -6,7 +6,7 @@
  */
 import * as path from "node:path";
 import { atlasWebUrl } from "./browser.js";
-import { commitDiff, execFileAsync, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, usableSummary, } from "./git.js";
+import { commitDiff, execFileAsync, FICHEROS_GENERADOS, GIT_MAX_BUFFER_BYTES, gitErrorMessage, MAX_DIFF_CHARACTERS, usableSummary, } from "./git.js";
 import { canonicalDiffHash } from "./canonical.js";
 import { optimizeTokensForAI, truncateAtFileBoundary } from "./optimize.js";
 export async function analyze(db, options = {}) {
@@ -124,7 +124,9 @@ async function commitMeta(cwd, ref) {
 }
 async function gitDiffHead(cwd) {
     try {
-        const { stdout } = await execFileAsync("git", ["diff", "HEAD", "-U0"], {
+        // Mismos ficheros excluidos que en commitDiff: el atlas no se analiza a sí
+        // mismo (ver FICHEROS_GENERADOS).
+        const { stdout } = await execFileAsync("git", ["diff", "HEAD", "-U0", "--", ...FICHEROS_GENERADOS], {
             cwd,
             encoding: "utf8",
             maxBuffer: GIT_MAX_BUFFER_BYTES,

package/dist/context.js

@@ -8,18 +8,58 @@
  * file that can go stale between commits: it is generated on the spot, per
  * session.
  *
- * FAIL-OPEN, ABSOLUTE. This runs on the critical path of opening a session.
- * Every failure mode — logged out, offline, no project, or merely slow — must
- * print NOTHING and exit 0. A broken or slow atlas can never block or delay a
- * user's session start. The whole body races a short timeout; on timeout or
- * any throw, we emit nothing.
+ * FAIL-OPEN, ABSOLUTE, in the sense that matters: this runs on the critical
+ * path of opening a session, so nothing here may ever block it, slow it, or
+ * exit non-zero. The whole body races a short timeout; on timeout or any
+ * throw, we emit nothing and exit 0.
+ *
+ * What is NO LONGER absolute is the silence. Failing quietly used to mean the
+ * agent opened a session with no atlas AND no idea why — and the commonest
+ * cause, a dead CLI session, is precisely when it most needs to know, because
+ * everything the atlas told it about recent work is stale. So the feed pulse
+ * (feed.ts) is emitted even when the brief itself cannot be built. Quiet
+ * failure and invisible failure are different things; only the first one was
+ * ever the goal.
  */
 import * as fs from "node:fs";
 import path from "node:path";
+import { feedWarningFor } from "./feed.js";
 import { fetchBriefSection } from "./sync.js";
 import { commitAliasesShort, derivaContraHead } from "./tools.js";
 /** Hard ceiling on the critical path: past this, emit nothing and move on. */
 const CONTEXT_TIMEOUT_MS = 2_000;
+/**
+ * A timeout that can lose the race without punishing the winner.
+ *
+ * The naive form — `new Promise(r => setTimeout(r, ms))` raced against the real
+ * work — has a bug that measurement makes obvious and reading never does: when
+ * the work wins, the timer is still pending, and Node will not exit until it
+ * fires. The process is done and just sits there. Measured 2026-07-26:
+ * `changebook context` took 2.18s wall clock to produce a payload it already had
+ * in ~200ms, on the session-start path, under a doc comment promising it would
+ * "never block it, slow it, or exit non-zero". It had been slowing every session
+ * by two seconds.
+ *
+ * `unref()` is the fix: the timer still fires if anything else is keeping the
+ * loop alive, but it never keeps the loop alive by itself. `cancelar()` is belt
+ * and braces for the long-lived case (the MCP server), where an unref'd timer
+ * would still fire pointlessly.
+ *
+ * Shared by both hooks on purpose. The defect existed independently in two
+ * places, which is the usual sign that the shape — not the instance — was wrong.
+ */
+export function presupuestoDeTiempo(ms) {
+    let cancelar = () => { };
+    const vencido = new Promise((resolve) => {
+        const t = setTimeout(() => resolve(null), ms);
+        t.unref?.();
+        cancelar = () => {
+            clearTimeout(t);
+            resolve(null);
+        };
+    });
+    return { vencido, cancelar };
+}
 async function buildPayload(db, dir) {
     // Logged out → silent no-op. A fresh clone with the hook installed but no
     // session must open exactly as fast as before.
@@ -52,24 +92,20 @@ async function buildPayload(db, dir) {
     }
     return drift ? `${section}\n\n${drift}` : section;
 }
-// ── SessionStart hook install (opt-in, per repo) ─────────────────────────────
-//
-// The push channel lives in `.claude/settings.json` under hooks.SessionStart.
-// Consent is the act of running `changebook hook-context install` (or saying
-// yes to init's offer) — this file is often committed and shared, so we NEVER
-// write it silently and NEVER clobber a config we can't parse.
 // `2>/dev/null || true`: if `changebook` isn't on PATH for some teammate, the
 // shell error is swallowed and the hook exits 0 — a missing binary must not
-// make a session-start hook look failed. printContext already emits only the
-// JSON payload (or nothing) on stdout.
-const HOOK_COMMAND = "changebook context 2>/dev/null || true";
-// Recognisable substring to find/remove our own entry without touching others.
-const HOOK_MARKER = "changebook context";
+// make a hook look failed. Both commands emit only the JSON payload (or
+// nothing) on stdout.
+export const CONTEXT_HOOK = {
+    event: "SessionStart",
+    command: "changebook context 2>/dev/null || true",
+    marker: "changebook context",
+};
 function settingsPath(dir) {
     return path.join(path.resolve(dir), ".claude", "settings.json");
 }
-function groupHasMarker(g) {
-    return (g.hooks ?? []).some((h) => (h.command ?? "").includes(HOOK_MARKER));
+function groupHasMarker(g, marker) {
+    return (g.hooks ?? []).some((h) => (h.command ?? "").includes(marker));
 }
 function readSettings(file) {
     let raw;
@@ -89,60 +125,103 @@ function readSettings(file) {
         return null; // unparseable → caller must refuse, never clobber
     }
 }
-export function contextHookInstalled(dir) {
+export function settingsHookInstalled(dir, spec) {
     const s = readSettings(settingsPath(dir));
-    return Boolean(s?.hooks?.SessionStart?.some(groupHasMarker));
+    return Boolean(s?.hooks?.[spec.event]?.some((g) => groupHasMarker(g, spec.marker)));
 }
-export function installContextHook(dir) {
+export function installSettingsHook(dir, spec) {
     const file = settingsPath(dir);
     const settings = readSettings(file);
     if (settings === null) {
         throw new Error(`Refusing to touch ${file}: it isn't valid JSON. Fix or remove it, then retry.`);
     }
     const hooks = (settings.hooks ??= {});
-    const sessionStart = (hooks.SessionStart ??= []);
-    if (sessionStart.some(groupHasMarker))
+    const list = (hooks[spec.event] ??= []);
+    if (list.some((g) => groupHasMarker(g, spec.marker)))
         return "already";
-    sessionStart.push({
-        hooks: [{ type: "command", command: HOOK_COMMAND }],
+    // El matcher solo se escribe si lo hay: un `matcher` presente y vacío es
+    // "todas las tools" en Claude Code, y en SessionStart no significa nada.
+    // Escribir la clave igualmente dejaría un campo mudo en un archivo que la
+    // gente lee y commitea.
+    list.push({
+        ...(spec.matcher ? { matcher: spec.matcher } : {}),
+        hooks: [{ type: "command", command: spec.command }],
     });
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
     return "installed";
 }
-export function uninstallContextHook(dir) {
+export function uninstallSettingsHook(dir, spec) {
     const file = settingsPath(dir);
     const settings = readSettings(file);
-    if (!settings || !settings.hooks?.SessionStart)
+    if (!settings?.hooks?.[spec.event])
         return "absent";
-    const before = settings.hooks.SessionStart;
+    const before = settings.hooks[spec.event];
     // Drop our command from every group, then drop groups left empty. Foreign
     // hooks in the same group (unusual, but possible) are preserved.
     const after = before
         .map((g) => ({
         ...g,
-        hooks: (g.hooks ?? []).filter((h) => !(h.command ?? "").includes(HOOK_MARKER)),
+        hooks: (g.hooks ?? []).filter((h) => !(h.command ?? "").includes(spec.marker)),
     }))
         .filter((g) => (g.hooks ?? []).length > 0);
-    if (after.length === before.length && before.every((g) => !groupHasMarker(g))) {
+    if (after.length === before.length &&
+        before.every((g) => !groupHasMarker(g, spec.marker))) {
         return "absent";
     }
     if (after.length > 0)
-        settings.hooks.SessionStart = after;
+        settings.hooks[spec.event] = after;
     else
-        delete settings.hooks.SessionStart;
+        delete settings.hooks[spec.event];
     if (Object.keys(settings.hooks).length === 0)
         delete settings.hooks;
     fs.writeFileSync(file, JSON.stringify(settings, null, 2) + "\n");
     return "removed";
 }
+// Envoltorios del canal SessionStart. Se mantienen con su nombre porque son la
+// superficie que ya consume index.ts (y, a través de él, `init`): generalizar
+// por dentro no es motivo para renombrar por fuera.
+export function contextHookInstalled(dir) {
+    return settingsHookInstalled(dir, CONTEXT_HOOK);
+}
+export function installContextHook(dir) {
+    return installSettingsHook(dir, CONTEXT_HOOK);
+}
+export function uninstallContextHook(dir) {
+    return uninstallSettingsHook(dir, CONTEXT_HOOK);
+}
+/**
+ * The pulse and the brief, composed. Separate from printContext so the WHOLE
+ * thing — including the pulse — stays inside the single timeout race: adding
+ * work outside it would erode the "never delays a session" guarantee.
+ *
+ * The two are gathered independently on purpose. Before this, a throw inside
+ * buildPayload took the whole payload down, and the most common cause of that
+ * throw is a dead session — which is exactly when the agent most needs to be
+ * told something. Now a broken brief still lets the pulse through.
+ */
+async function buildSessionContext(db, dir) {
+    // Local and offline: one small file plus a git rev-parse. It cannot fail
+    // because of the network or the session, which is the point.
+    const pulse = await feedWarningFor(dir, { audience: "agent" }).catch(() => "");
+    let brief = null;
+    try {
+        brief = await buildPayload(db, dir);
+    }
+    catch {
+        brief = null;
+    }
+    const parts = [pulse, brief].filter(Boolean);
+    return parts.length > 0 ? parts.join("\n\n") : null;
+}
 export async function printContext(db, dir) {
     try {
-        const timeout = new Promise((resolve) => setTimeout(() => resolve(null), CONTEXT_TIMEOUT_MS));
+        const { vencido, cancelar } = presupuestoDeTiempo(CONTEXT_TIMEOUT_MS);
         const additionalContext = await Promise.race([
-            buildPayload(db, dir),
-            timeout,
+            buildSessionContext(db, dir),
+            vencido,
         ]);
+        cancelar();
         if (!additionalContext)
             return;
         // The SessionStart contract: stdout JSON whose additionalContext is

package/dist/credentials.js

@@ -61,6 +61,48 @@ export function clearCredentials() {
         return false;
     }
 }
+const INFLIGHT_FILE = path.join(DIR, "refresh-inflight.json");
+/**
+ * Deja constancia en disco de que ALGUIEN va a gastar el refresh token.
+ *
+ * Supabase lo rota **al recibir la peticion**, asi que entre "sale la peticion"
+ * y "guardamos el token nuevo" hay una ventana en la que el token del disco ya
+ * esta muerto sin que nadie lo sepa. Si el proceso no sobrevive a esa ventana
+ * —el `analyze` post-commit corre desacoplado en segundo plano, y basta con
+ * apagar el equipo o matar la terminal— el siguiente arranque reenvia el viejo,
+ * Supabase lo trata como robo y cierra la sesion.
+ *
+ * Esta marca no PUEDE evitarlo: nada del lado del cliente sobrevive a un
+ * `kill -9`. Lo que evita es que sea inexplicable. Sin ella, el usuario ve
+ * "Invalid Refresh Token: Already Used" y no tiene forma de saber por que; con
+ * ella se le puede decir cuando se quedo a medias la renovacion.
+ */
+export function markRefreshInFlight(now = new Date()) {
+    try {
+        fs.mkdirSync(DIR, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(INFLIGHT_FILE, JSON.stringify({ at: now.toISOString(), pid: process.pid }), { mode: 0o600 });
+    }
+    catch {
+        // Es un diagnostico, no una garantia: si no se puede escribir, seguimos.
+    }
+}
+export function clearRefreshInFlight() {
+    try {
+        fs.rmSync(INFLIGHT_FILE, { force: true });
+    }
+    catch {
+        // idem
+    }
+}
+export function readRefreshInFlight() {
+    try {
+        const data = JSON.parse(fs.readFileSync(INFLIGHT_FILE, "utf8"));
+        return typeof data.at === "string" ? data : null;
+    }
+    catch {
+        return null;
+    }
+}
 const LOCK_FILE = path.join(DIR, "refresh.lock");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/feed.js

@@ -0,0 +1,147 @@
+/**
+ * The atlas' feed pulse: did the automatic ingestion actually land?
+ *
+ * The post-commit hook runs detached and never blocks the commit (see hook.ts),
+ * which is the right call — but it means that when it fails (expired session,
+ * offline, out of credits) NOTHING surfaces. The atlas just stops learning, and
+ * the only symptom is data that looks slightly old, which is indistinguishable
+ * from "nothing has happened". A tool whose whole job is to notice silent
+ * decay must not decay silently itself.
+ *
+ * Real case that motivated this (2026-07-25): the stored session died, two
+ * commits in a row fed nothing, and the failure was only found by reading a log
+ * nobody had a reason to open — by which point the first failure's evidence had
+ * already been overwritten by the second.
+ *
+ * The contract is deliberately one-directional and cheap:
+ *   `analyze --commit` (the hook path) records the outcome here.
+ *   `guard` (pre-commit, FOREGROUND, a human is watching) reads it and says it
+ *   out loud at the next commit.
+ *
+ * Everything here is best-effort: a read-only .git, a corrupt file or a missing
+ * git must never turn into a failed commit. Losing the pulse is bad; breaking
+ * someone's commit to report it would be worse.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { gitPath } from "./git.js";
+const FEED_FILE = "changebook-feed.json";
+/** Where the post-commit hook keeps the full output; cited in the warning. */
+export const HOOK_LOG_FILE = "changebook-hook.log";
+const MAX_REASON_CHARS = 200;
+/**
+ * The first paragraph of an error, which is the part that says what went wrong.
+ * Several of our errors append a blank line and then the multi-line AUTH_HELP;
+ * collapsing all of that into one line produced a warning whose "Last error:"
+ * trailed off mid-sentence into the help text ("… Run: changebook login It
+ * opens https:"). The remedy line already tells the user what to do.
+ */
+function firstParagraph(reason) {
+    return reason.split(/\n\s*\n/)[0].replace(/\s+/g, " ").trim();
+}
+export async function feedStatusPath(dir) {
+    return gitPath(dir, FEED_FILE).catch(() => null);
+}
+export async function readFeedStatus(dir) {
+    try {
+        const file = await feedStatusPath(dir);
+        if (!file)
+            return null;
+        const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        // A hand-edited or half-written file must not crash a commit: accept it
+        // only if the two fields the warning depends on are the right shape.
+        if (typeof data.ok !== "boolean" || typeof data.failures !== "number") {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record how the automatic feed went. Failures accumulate a streak so the
+ * warning can say "the last 4 commits" instead of only ever "the last one" —
+ * the difference between a blip you can ignore and a week of silence you can't.
+ */
+export async function recordFeed(dir, result, now = new Date()) {
+    try {
+        const file = await feedStatusPath(dir);
+        if (!file)
+            return;
+        const previous = await readFeedStatus(dir);
+        const at = now.toISOString();
+        const status = result.ok
+            ? { ok: true, at, failures: 0 }
+            : {
+                ok: false,
+                at,
+                failures: (previous?.ok === false ? previous.failures : 0) + 1,
+                since: previous?.ok === false ? (previous.since ?? at) : at,
+                reason: result.reason
+                    ? firstParagraph(result.reason).slice(0, MAX_REASON_CHARS)
+                    : undefined,
+            };
+        fs.writeFileSync(file, JSON.stringify(status));
+    }
+    catch {
+        // Best-effort: never let bookkeeping break a commit.
+    }
+}
+/** A session problem is the one failure the user can fix in one command. */
+function needsLogin(reason) {
+    return /session|refresh[_ ]token|logged out|no stored session|\b40[13]\b/i.test(reason ?? "");
+}
+function remedyFor(reason) {
+    return needsLogin(reason)
+        ? "changebook login"
+        : "changebook analyze --commit HEAD   (to see the error in full)";
+}
+/**
+ * The warning a human sees, as text. Built separately from printing it so it
+ * can be tested, same shape as guard.ts' findingsMessage. Empty string when
+ * there is nothing to say — a healthy feed must stay completely silent, or the
+ * warning becomes noise people learn to skip.
+ */
+export function feedWarning(status, opts = {}) {
+    const { logPath = `.git/${HOOK_LOG_FILE}`, audience = "human" } = opts;
+    if (!status || status.ok || status.failures < 1)
+        return "";
+    const commits = status.failures === 1
+        ? "The last commit was not analyzed"
+        : `The last ${status.failures} commits were not analyzed`;
+    const since = status.since ? ` (since ${status.since.slice(0, 16).replace("T", " ")} UTC)` : "";
+    if (audience === "agent") {
+        const lines = [
+            "⚠ ChangeBook: this project's atlas is NOT being fed.",
+            `${commits}${since}, so anything it tells you about recent work is out of date — say so before you rely on it.`,
+        ];
+        if (status.reason)
+            lines.push(`Last error: ${status.reason}`);
+        lines.push(needsLogin(status.reason)
+            ? "Tell the user to run `changebook login` in their terminal. It opens a browser to authorize, so you cannot complete it yourself."
+            : `Tell the user their atlas stopped updating; the full error is in ${logPath}.`);
+        return lines.join("\n");
+    }
+    const lines = [
+        "\n⚠ ChangeBook: your atlas has stopped being fed.",
+        `  ${commits}${since}, so what it tells you is going stale.`,
+    ];
+    if (status.reason)
+        lines.push(`  Last error: ${status.reason}`);
+    lines.push(`  Fix: ${remedyFor(status.reason)}`);
+    lines.push(`  Full output: ${logPath}\n`);
+    return lines.join("\n");
+}
+/** Convenience for callers that only want the text for a directory. */
+export async function feedWarningFor(dir, opts = {}) {
+    const status = await readFeedStatus(dir);
+    if (!status || status.ok)
+        return "";
+    const file = await feedStatusPath(dir);
+    const logPath = file
+        ? path.join(path.dirname(file), HOOK_LOG_FILE)
+        : `.git/${HOOK_LOG_FILE}`;
+    return feedWarning(status, { ...opts, logPath });
+}
+//# sourceMappingURL=feed.js.map

package/dist/git.js

@@ -5,8 +5,22 @@
  * compress differently across subcommands and break the server-side dedup.
  */
 import { execFile } from "node:child_process";
+import * as path from "node:path";
 import { promisify } from "node:util";
 export const execFileAsync = promisify(execFile);
+/**
+ * Absolute path to a file inside this repo's git dir (the guard's cache, the
+ * feed pulse, the hook log). `--git-path` rather than building
+ * `<git-dir>/<name>` by hand: it resolves a linked worktree's common dir, so
+ * every process that shares the repo agrees on where these files live.
+ */
+export async function gitPath(dir, name) {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", name], {
+        cwd: dir,
+        encoding: "utf8",
+    });
+    return path.resolve(dir, stdout.trim());
+}
 export const GIT_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 // Mirror of the extension's default changebook.maxDiffCharacters (the server
 // rejects anything above 60k anyway).
@@ -46,12 +60,44 @@ export function usableSummary(message) {
     return (lastBreak > MIN_USEFUL_SUMMARY_CHARS ? cut.slice(0, lastBreak) : cut).trim();
 }
 /** `git show <hash> -U0` — the unified diff of a single commit, no context. */
+/**
+ * Ficheros que ESCRIBE el propio ChangeBook y que por tanto no puede analizar.
+ *
+ * `sync` regenera el bloque del mapa dentro de CLAUDE.md/AGENTS.md, y `analyze`
+ * lo dispara en cada commit. Sin excluirlos se cierra un bucle: commiteas el
+ * mapa regenerado -> el análisis lo ve -> nace/actualiza el módulo "Mapeo de
+ * módulos" -> pasa a ser el más reciente -> el mapa se reordena -> vuelve a
+ * estar sucio. Cuesta un diff de una línea cada dos por tres y el 2026-07-25
+ * costó un conflicto de merge real.
+ *
+ * No es una preferencia de ruido: una herramienta que se mide a sí misma
+ * inventa actividad que no existe. Los 6 "cambios" del módulo del mapa son
+ * exactamente eso.
+ *
+ * Un commit que SOLO toca estos ficheros produce un diff vacío y `analyze` lo
+ * salta con su mensaje de siempre — que es la respuesta correcta: regenerar el
+ * mapa no es un cambio de producto.
+ */
+export const FICHEROS_GENERADOS = [
+    ":(exclude)CLAUDE.md",
+    ":(exclude)AGENTS.md",
+    ":(exclude)**/CLAUDE.md",
+    ":(exclude)**/AGENTS.md",
+];
 export async function commitDiff(cwd, hash) {
     try {
         const { stdout } = await execFileAsync("git", 
         // --end-of-options so a ref that starts with "-" (e.g. "-n5") is treated
         // as a revision, never as a git option (argument injection).
-        ["show", "--pretty=format:", "-U0", "--end-of-options", hash], { cwd, encoding: "utf8", maxBuffer: GIT_MAX_BUFFER_BYTES });
+        [
+            "show",
+            "--pretty=format:",
+            "-U0",
+            "--end-of-options",
+            hash,
+            "--",
+            ...FICHEROS_GENERADOS,
+        ], { cwd, encoding: "utf8", maxBuffer: GIT_MAX_BUFFER_BYTES });
         return stdout;
     }
     catch (error) {

package/dist/guard.js

@@ -15,7 +15,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
-import { execFileAsync } from "./git.js";
+import { execFileAsync, gitPath } from "./git.js";
+import { feedWarningFor } from "./feed.js";
 /** Exit code that asks the pre-commit hook to abort the commit. */
 export const EXIT_BLOCK = 3;
 // A commit should never feel slow because of us: whatever the network hasn't
@@ -200,10 +201,6 @@ export function contarEnRepo(dir, simbolo) {
         return code === 1 ? 0 : null;
     }
 }
-async function gitPath(dir, name) {
-    const { stdout } = await execFileAsync("git", ["rev-parse", "--git-path", name], { cwd: dir, encoding: "utf8" });
-    return path.resolve(dir, stdout.trim());
-}
 export async function stagedFiles(dir) {
     // -z: NUL-separated, and crucially git does NOT octal-quote non-ASCII paths
     // (default quotepath would emit "m\303\263dulo.ts", which never matches the
@@ -273,11 +270,29 @@ async function fetchSignals(db, dir, env) {
     }
     return { alerts, filesByModule, projectId, fromCache: false };
 }
-/** One-line last-run trace so "why didn't it warn?" is answerable. */
+// Un fallo intermitente no se diagnostica con la última foto: hace falta la
+// racha. Este log guardaba SOLO la última corrida, y el 2026-07-25 eso costó un
+// diagnóstico — la corrida que gastó la sesión ya había sido pisada por la
+// siguiente cuando fui a mirar. Acotado por tamaño, no por olvido.
+const GUARD_LOG_MAX_BYTES = 65_536;
+const GUARD_LOG_KEEP_BYTES = 32_768;
+/** Traza por corrida, en append acotado, para que "¿por qué no avisó?" tenga respuesta. */
 async function logRun(dir, message) {
     try {
         const file = await gitPath(dir, "changebook-guard.log");
-        fs.writeFileSync(file, `${new Date().toISOString()} ${message}\n`);
+        // Recortar ANTES de anexar: con appendFileSync no hay descriptor abierto de
+        // por medio, pero el orden mantiene el fichero por debajo del techo aunque
+        // esta corrida escriba una línea larga.
+        try {
+            if (fs.statSync(file).size > GUARD_LOG_MAX_BYTES) {
+                const keep = fs.readFileSync(file).subarray(-GUARD_LOG_KEEP_BYTES);
+                fs.writeFileSync(file, keep);
+            }
+        }
+        catch {
+            // El fichero aún no existe: nada que recortar.
+        }
+        fs.appendFileSync(file, `${new Date().toISOString()} ${message}\n`);
     }
     catch {
         // Best-effort only.
@@ -314,6 +329,14 @@ export async function runGuard(db, dir, env = process.env) {
     const mode = (env.CHANGEBOOK_GUARD ?? "").trim().toLowerCase();
     if (mode === "off")
         return 0;
+    // The atlas' feed pulse, FIRST and offline. This is the one warning that has
+    // to survive a dead session — a dead session is its most common cause, and
+    // every check below this point either needs credentials or the network. It
+    // reads one small file, so it cannot slow a commit down, and like everything
+    // else here it only informs: the exit code is untouched.
+    const pulse = await feedWarningFor(dir);
+    if (pulse)
+        console.error(pulse);
     if (!db.hasCredentials())
         return 0;
     let staged;

package/dist/hook.js

@@ -22,16 +22,34 @@ function cliEntry() {
 }
 const POST_COMMIT_MARKER = "# changebook post-commit hook";
 const PRE_COMMIT_MARKER = "# changebook pre-commit guard";
+// The hook log grows by one run per commit, so it needs a ceiling — but one
+// that keeps enough history to diagnose a streak of failures, which is the
+// whole reason it is worth keeping at all.
+const LOG_MAX_BYTES = 262_144;
+const LOG_TRIM_KEEP_BYTES = 131_072;
 /** Exported for tests: the contract between this script and guard.ts. */
 export function postCommitScript() {
     // Background subshell + `|| true`: a broken analyze (offline, out of
     // credits, logged out) must never make `git commit` fail or feel slow.
-    // The log keeps only the last run so it can't grow unbounded.
+    //
+    // The log APPENDS, with a UTC header per run. It used to keep only the last
+    // run to stay bounded, which cost us a real diagnosis on 2026-07-25: two
+    // commits failed in a row and the second overwrote the evidence of the first,
+    // so which process broke the session was no longer answerable. Bounded is
+    // still right, but by trimming — not by forgetting everything but the last
+    // line. The trim runs BEFORE the redirection opens on purpose: replacing the
+    // file while the append fd is already open would leave that fd pointing at
+    // the unlinked inode and silently throw the run's output away.
+    const trimmed = `${LOG_TRIM_KEEP_BYTES}`;
     return `#!/bin/sh
 ${POST_COMMIT_MARKER} — analyzes each commit into your ChangeBook atlas.
 # Runs in the background and never blocks the commit. Remove with:
 #   changebook hook uninstall
-( ${JSON.stringify(process.execPath)} ${JSON.stringify(cliEntry())} analyze --commit HEAD > "$(git rev-parse --git-dir)/changebook-hook.log" 2>&1 & ) || true
+LOG="$(git rev-parse --git-path changebook-hook.log)"
+if [ -f "$LOG" ] && [ "$(wc -c < "$LOG")" -gt ${LOG_MAX_BYTES} ]; then
+  tail -c ${trimmed} "$LOG" > "$LOG.tmp" 2>/dev/null && mv -f "$LOG.tmp" "$LOG"
+fi
+( { date -u +'=== %Y-%m-%dT%H:%M:%SZ'; ${JSON.stringify(process.execPath)} ${JSON.stringify(cliEntry())} analyze --commit HEAD; } >> "$LOG" 2>&1 & ) || true
 `;
 }
 /** Exported for tests: the contract between this script and guard.ts. */