@trazum/cli 1.47.0 → 1.48.0

package/dist/waiver-log.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where a waiver's uses are written down.
+ *
+ * The core decides what a use means and what a run of them adds up to; this
+ * decides where the bytes go — the same split every module here follows, so
+ * `@trazum/core` stays browser-safe and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, and never rewritten.** There is deliberately no prune, no
+ * compaction and no `--clear`: a record of decisions that the tool can erase
+ * is a record nobody can rely on, and the one thing a waiver history is for is
+ * being awkward six months later. Deleting the file is a thing a person does
+ * with `rm`, on purpose, having seen it.
+ *
+ * **A write that fails never fails the run.** The gate's job is the exit code.
+ * A read-only checkout, a full disk or a directory somebody's CI cannot create
+ * must not turn a passing build red on account of bookkeeping — the failure is
+ * reported and the gate's own verdict stands.
+ *
+ * **A line that will not parse is counted and skipped**, exactly as in the
+ * store. Losing the whole history because one line is broken would be the
+ * worst possible response; pretending the history is complete would be the
+ * second worst.
+ */
+import type { WaiverUse } from '@trazum/core';
+/** One file, not one per month: a waiver history is small and read whole. */
+export declare const WAIVER_LOG = ".trazum/waivers.jsonl";
+export interface WaiverReadResult {
+    uses: WaiverUse[];
+    /** 1-based positions of lines that would not parse. Named, never dropped quietly. */
+    unreadable: number[];
+    /** False when the file does not exist — "nothing recorded" is not "no file". */
+    present: boolean;
+}
+export declare function readWaiverLog(root: string): Promise<WaiverReadResult>;
+/**
+ * Appends one use, and swallows any failure after reporting it.
+ *
+ * Returns the error message rather than throwing, so the caller can print it
+ * beside the gate's own output without the gate ever depending on the write.
+ */
+export declare function appendWaiverUse(root: string, use: WaiverUse): Promise<string | null>;
+//# sourceMappingURL=waiver-log.d.ts.map

package/dist/waiver-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"waiver-log.d.ts","sourceRoot":"","sources":["../src/waiver-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,6EAA6E;AAC7E,eAAO,MAAM,UAAU,0BAA0B,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,qFAAqF;IACrF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuB3E;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAS1F"}

package/dist/waiver-log.js

@@ -0,0 +1,74 @@
+/**
+ * Where a waiver's uses are written down.
+ *
+ * The core decides what a use means and what a run of them adds up to; this
+ * decides where the bytes go — the same split every module here follows, so
+ * `@trazum/core` stays browser-safe and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, and never rewritten.** There is deliberately no prune, no
+ * compaction and no `--clear`: a record of decisions that the tool can erase
+ * is a record nobody can rely on, and the one thing a waiver history is for is
+ * being awkward six months later. Deleting the file is a thing a person does
+ * with `rm`, on purpose, having seen it.
+ *
+ * **A write that fails never fails the run.** The gate's job is the exit code.
+ * A read-only checkout, a full disk or a directory somebody's CI cannot create
+ * must not turn a passing build red on account of bookkeeping — the failure is
+ * reported and the gate's own verdict stands.
+ *
+ * **A line that will not parse is counted and skipped**, exactly as in the
+ * store. Losing the whole history because one line is broken would be the
+ * worst possible response; pretending the history is complete would be the
+ * second worst.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isWaiverUse } from '@trazum/core';
+/** One file, not one per month: a waiver history is small and read whole. */
+export const WAIVER_LOG = '.trazum/waivers.jsonl';
+export async function readWaiverLog(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, WAIVER_LOG), 'utf8');
+    }
+    catch {
+        // Absent is the normal state of a repository that has never waived
+        // anything, and it is not an error.
+        return { uses: [], unreadable: [], present: false };
+    }
+    const uses = [];
+    const unreadable = [];
+    raw.split('\n').forEach((line, index) => {
+        if (line.trim() === '')
+            return;
+        try {
+            const parsed = JSON.parse(line);
+            if (isWaiverUse(parsed))
+                uses.push(parsed);
+            else
+                unreadable.push(index + 1);
+        }
+        catch {
+            unreadable.push(index + 1);
+        }
+    });
+    return { uses, unreadable, present: true };
+}
+/**
+ * Appends one use, and swallows any failure after reporting it.
+ *
+ * Returns the error message rather than throwing, so the caller can print it
+ * beside the gate's own output without the gate ever depending on the write.
+ */
+export async function appendWaiverUse(root, use) {
+    const path = join(root, WAIVER_LOG);
+    try {
+        await mkdir(join(path, '..'), { recursive: true });
+        await writeFile(path, `${JSON.stringify(use)}\n`, { flag: 'a', mode: 0o600 });
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+//# sourceMappingURL=waiver-log.js.map

package/dist/waiver-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waiver-log.js","sourceRoot":"","sources":["../src/waiver-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAG3C,6EAA6E;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,uBAAuB,CAAC;AAUlD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY;IAC9C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,oCAAoC;QACpC,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,IAAI,GAAgB,EAAE,CAAC;IAC7B,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACtC,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO;QAC/B,IAAI,CAAC;YACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,WAAW,CAAC,MAAM,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;;gBACtC,UAAU,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,UAAU,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,GAAc;IAChE,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC9E,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.47.0"
+    "@trazum/core": "1.48.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -1554,6 +1554,8 @@ ${bold('EXAMPLES')}
       `WAIVED — the ${gate} failure above is on the record and silenced until ${until} (${daysLeft} days left): "${reason}". The bill still counts it; only the exit code is quiet, and the day the waiver expires this gate fails again.`,
     waiveExpired: (gate, until, reason) =>
       `The waiver on ${gate} expired on ${until} and no longer silences anything. It was written for: "${reason}". Renew it with a new date and a current reason, or fix what it was covering — an expired waiver left in place is a finding deleted with extra steps.`,
+    waiveNotRecorded: (path, because) =>
+      `  (This waiver was not written to ${path}: ${because}. The gate's verdict above is unaffected.)`,
     summaryNoComparison: () =>
       'No previous log was given, so nothing here says whether the bill moved — a summary without a comparison states the bill, not its stability.',
     summaryFooter: () =>
@@ -1807,6 +1809,33 @@ ${bold('EXAMPLES')}
     unrecognized: (name) => `${name} is neither a stored report nor a saved plan, so it is in no series above.`,
     footer: () =>
       'A series names shapes, not futures. Twenty points make a trend visible; they do not make next month knowable — where these lines go next is yours to judge.',
+    waiverHeading: () => 'What this repository has been living with',
+    waiverSince: (day, uses) =>
+      `${uses} recorded ${uses === 1 ? 'use' : 'uses'} since ${day}, when recording started.`,
+    waiverNoneRecorded: () =>
+      'No waiver has silenced a gate since recording started. Nothing here is inferred from the config — a waiver written down and never hit is not a decision anyone is living with.',
+    waiverHabit: (gate, uses, days, firstDay, lastDay) =>
+      `${gate}: ${uses} ${uses === 1 ? 'use' : 'uses'} across ${days} ${days === 1 ? 'day' : 'days'}, ${firstDay} to ${lastDay}`,
+    waiverVerdict: (verdict) =>
+      verdict === 'used-once'
+        ? 'Used once. Nothing to read into it yet.'
+        : verdict === 'recurring'
+          ? 'The same decision, holding. The gate keeps firing and the reason has not moved.'
+          : verdict === 'renewed-without-revisiting'
+            ? 'The expiry has moved and the reason has not. That is the shape a decision takes when nobody is revisiting it — which is sometimes exactly right, and worth saying out loud either way.'
+            : 'The reason changed between uses. Somebody looked again.',
+    waiverReasonNow: (reason) => `Reason: ${reason}`,
+    waiverReasonsChanged: (count) => `${count} different reasons given over that time.`,
+    waiverExpiriesMoved: (from, to, count) =>
+      `Expiry moved ${count} ${count === 1 ? 'time' : 'times'}: ${from} → ${to}.`,
+    waiverNoLongerConfigured: () =>
+      'Not in the config any more. The decision was reversed; the record keeps it.',
+    waiverNeverUsed: (gates) =>
+      `Waived in the config and never hit by a recorded run: ${gates}. Either the gate stopped failing — good news nobody wrote down — or the waiver names a situation that does not arise. Both are worth deleting.`,
+    waiverUnreadable: (count, path) =>
+      `${count} ${count === 1 ? 'line' : 'lines'} in ${path} could not be read and are not counted above.`,
+    waiverStartsHere: () =>
+      'Nothing before that day exists. This record began when recording did, and no past was reconstructed from the config as it stands.',
   },
 
   verify: {

package/src/i18n/es.ts

@@ -1584,6 +1584,8 @@ ${bold('EJEMPLOS')}
       `WAIVED — el fallo de ${gate} de arriba queda registrado y silenciado hasta ${until} (${daysLeft} días restantes): "${reason}". La factura lo sigue contando; solo el código de salida calla, y el día que caduque el waiver este gate vuelve a fallar.`,
     waiveExpired: (gate, until, reason) =>
       `El waiver de ${gate} caducó el ${until} y ya no silencia nada. Se escribió por: "${reason}". Renuévalo con fecha nueva y razón vigente, o arregla lo que cubría — un waiver caducado dejado ahí es un hallazgo borrado con pasos extra.`,
+    waiveNotRecorded: (path, because) =>
+      `  (Este waiver no se pudo escribir en ${path}: ${because}. El veredicto de la puerta de arriba no cambia.)`,
     summaryNoComparison: () =>
       'No se dio un registro anterior, así que nada de aquí dice si la factura se movió — un resumen sin comparación indica la factura, no su estabilidad.',
     summaryFooter: () =>
@@ -1837,6 +1839,33 @@ ${bold('EJEMPLOS')}
     unrecognized: (name) => `${name} no es ni un informe guardado ni un plan guardado, así que no está en ninguna serie de arriba.`,
     footer: () =>
       'Una serie nombra formas, no futuros. Veinte puntos hacen visible una tendencia; no hacen conocible el mes que viene — adónde van estas líneas después lo juzgas tú.',
+    waiverHeading: () => 'Con lo que este repositorio ha estado conviviendo',
+    waiverSince: (day, uses) =>
+      `${uses} ${uses === 1 ? 'uso registrado' : 'usos registrados'} desde el ${day}, cuando empezó el registro.`,
+    waiverNoneRecorded: () =>
+      'Ningún waiver ha silenciado una puerta desde que empezó el registro. Nada de aquí se deduce de la configuración — un waiver escrito y nunca usado no es una decisión con la que nadie conviva.',
+    waiverHabit: (gate, uses, days, firstDay, lastDay) =>
+      `${gate}: ${uses} ${uses === 1 ? 'uso' : 'usos'} en ${days} ${days === 1 ? 'día' : 'días'}, del ${firstDay} al ${lastDay}`,
+    waiverVerdict: (verdict) =>
+      verdict === 'used-once'
+        ? 'Usado una vez. Todavía no hay nada que leer en ello.'
+        : verdict === 'recurring'
+          ? 'La misma decisión, sosteniéndose. La puerta sigue saltando y el motivo no ha cambiado.'
+          : verdict === 'renewed-without-revisiting'
+            ? 'La fecha de caducidad se ha movido y el motivo no. Esa es la forma que toma una decisión que nadie está revisando — a veces es exactamente lo correcto, y merece decirse en voz alta igualmente.'
+            : 'El motivo cambió entre usos. Alguien volvió a mirarlo.',
+    waiverReasonNow: (reason) => `Motivo: ${reason}`,
+    waiverReasonsChanged: (count) => `${count} motivos distintos dados en ese tiempo.`,
+    waiverExpiriesMoved: (from, to, count) =>
+      `La caducidad se movió ${count} ${count === 1 ? 'vez' : 'veces'}: ${from} → ${to}.`,
+    waiverNoLongerConfigured: () =>
+      'Ya no está en la configuración. La decisión se revirtió; el registro la conserva.',
+    waiverNeverUsed: (gates) =>
+      `Con waiver en la configuración y nunca usados por una ejecución registrada: ${gates}. O la puerta dejó de fallar — buenas noticias que nadie anotó — o el waiver nombra una situación que no ocurre. Ambos merecen borrarse.`,
+    waiverUnreadable: (count, path) =>
+      `${count} ${count === 1 ? 'línea' : 'líneas'} de ${path} no se pudieron leer y no cuentan arriba.`,
+    waiverStartsHere: () =>
+      'Nada anterior a ese día existe. Este registro empezó cuando empezó a registrarse, y no se reconstruyó ningún pasado a partir de la configuración actual.',
   },
 
   verify: {

package/src/i18n/types.ts

@@ -877,6 +877,14 @@ export interface CliMessages {
      */
     waiveActive(gate: string, reason: string, until: string, daysLeft: string): string;
     waiveExpired(gate: string, until: string, reason: string): string;
+    /**
+     * A use that could not be written down.
+     *
+     * Printed dim and never as an error: the gate's verdict is unaffected, and
+     * a read-only checkout must not turn a passing build red on account of
+     * bookkeeping.
+     */
+    waiveNotRecorded(path: string, because: string): string;
     /**
      * `--markdown-summary`: the short form for a pull-request body or a weekly
      * note. A view over the same report, never a different set of figures.
@@ -1254,6 +1262,19 @@ export interface CliMessages {
     undated(name: string): string;
     unrecognized(name: string): string;
     footer(): string;
+    /** The waiver record — what this team has been living with, and for how long. */
+    waiverHeading(): string;
+    waiverSince(day: string, uses: number): string;
+    waiverNoneRecorded(): string;
+    waiverHabit(gate: string, uses: number, days: number, firstDay: string, lastDay: string): string;
+    waiverVerdict(verdict: string): string;
+    waiverReasonNow(reason: string): string;
+    waiverReasonsChanged(count: number): string;
+    waiverExpiriesMoved(from: string, to: string, count: number): string;
+    waiverNoLongerConfigured(): string;
+    waiverNeverUsed(gates: string): string;
+    waiverUnreadable(count: number, path: string): string;
+    waiverStartsHere(): string;
   };
 
   /**

package/src/index.ts

@@ -38,6 +38,8 @@ import {
   detectFromSource,
   matchLocale,
   parsePlanDocument,
+  waiverDay,
+  waiverHistory,
   proposeInit,
   MIN_RATE_DAYS,
   parseConfig,
@@ -126,6 +128,7 @@ import type {
 } from '@trazum/core';
 import type {
   UsageProfileReport,
+  WaiverUse,
   InitDecline,
   InitJustification,
   InitObservations,
@@ -168,6 +171,7 @@ import {
 import type { Revision } from './git.js';
 import { fetchProviderUsage, findCredential } from './connect.js';
 import { STORE_DIR, appendRecords, readStore, rewriteStore } from './store-fs.js';
+import { WAIVER_LOG, appendWaiverUse, readWaiverLog } from './waiver-log.js';
 import { DEFAULT_PORT, buildServer, listen } from './serve.js';
 import {
   WATCH_STATE_VERSION,
@@ -3348,7 +3352,12 @@ async function commandConnect(
  * same action planned twice — and no series, however long, becomes a
  * forecast.
  */
-async function commandHistory(args: Args, pricing: PricingCatalogue, t: CliMessages): Promise<void> {
+async function commandHistory(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
   /**
    * `--store` builds the series from measured spend already on disk.
    *
@@ -3452,7 +3461,23 @@ async function commandHistory(args: Args, pricing: PricingCatalogue, t: CliMessa
     throw new Error(t.history.needsThree(String(history.periods.length)));
   }
 
-  const stamped = { ...history, unrecognizedFiles: unrecognized };
+  /**
+   * The waiver record — closing the gap 1.40 named and could not fill.
+   *
+   * 1.40 wanted to say "this finding has been waived three times in a row" and
+   * refused to, because the only material available was the config as it
+   * stands, and a past reconstructed from a present is a guess wearing a
+   * record's clothes. The material exists now: since 1.48 a waiver that
+   * silences a gate writes down that it did, and this reads those lines back.
+   *
+   * Read from the working directory rather than from the reports directory:
+   * the waiver record belongs to the repository whose gates fired, and the
+   * stored reports may have come from anywhere.
+   */
+  const waivers = await readWaiverLog('.');
+  const waiverReport = waiverHistory(waivers.uses, config.waive ?? []);
+
+  const stamped = { ...history, unrecognizedFiles: unrecognized, waivers: waiverReport };
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const day = (ms: number): string => new Date(ms).toISOString().slice(0, 10);
   const pct = (value: number): string => `${(value * 100).toFixed(1)}%`;
@@ -3506,6 +3531,58 @@ async function commandHistory(args: Args, pricing: PricingCatalogue, t: CliMessa
     for (const name of unrecognized) {
       out.push(md ? `- ${t.history.unrecognized(name)}` : `  ${t.history.unrecognized(name)}`);
     }
+    /**
+     * The waiver record, printed only once something has been recorded.
+     *
+     * Silent on a repository that has never waived anything, rather than a
+     * heading over "0 uses" — an empty section teaches a reader to skip the
+     * section, and this is the one they should not learn to skip.
+     */
+    if (waivers.present) {
+      out.push('');
+      out.push(md ? `### ${t.history.waiverHeading()}` : t.history.waiverHeading());
+      if (waiverReport.totalUses === 0) {
+        out.push(md ? `- ${t.history.waiverNoneRecorded()}` : `  ${t.history.waiverNoneRecorded()}`);
+      } else {
+        const since = t.history.waiverSince(waiverReport.since ?? '', waiverReport.totalUses);
+        out.push(md ? `- ${since}` : `  ${since}`);
+        out.push(md ? `- _${t.history.waiverStartsHere()}_` : `  ${t.history.waiverStartsHere()}`);
+        for (const habit of waiverReport.habits) {
+          out.push('');
+          const head = t.history.waiverHabit(
+            habit.gate,
+            habit.uses,
+            habit.days,
+            habit.firstDay,
+            habit.lastDay,
+          );
+          out.push(md ? `- **${head}**` : `  ${head}`);
+          const rows = [t.history.waiverVerdict(habit.verdict)];
+          // The reason as it stands *now* — never read backwards onto an
+          // older use, which is the same mistake the record exists to avoid.
+          const latest = habit.reasons[habit.reasons.length - 1];
+          if (latest !== undefined) rows.push(t.history.waiverReasonNow(latest));
+          if (habit.reasons.length > 1) rows.push(t.history.waiverReasonsChanged(habit.reasons.length));
+          const firstExpiry = habit.expiries[0];
+          const lastExpiry = habit.expiries[habit.expiries.length - 1];
+          if (habit.expiries.length > 1 && firstExpiry !== undefined && lastExpiry !== undefined) {
+            rows.push(t.history.waiverExpiriesMoved(firstExpiry, lastExpiry, habit.expiries.length - 1));
+          }
+          if (!habit.stillConfigured) rows.push(t.history.waiverNoLongerConfigured());
+          for (const row of rows) out.push(md ? `  - ${row}` : `    ${row}`);
+        }
+      }
+      if (waiverReport.neverUsed.length > 0) {
+        out.push('');
+        const dead = t.history.waiverNeverUsed(waiverReport.neverUsed.join(', '));
+        out.push(md ? `- ${dead}` : `  ${dead}`);
+      }
+      if (waivers.unreadable.length > 0) {
+        const bad = t.history.waiverUnreadable(waivers.unreadable.length, WAIVER_LOG);
+        out.push(md ? `- ${bad}` : `  ${bad}`);
+      }
+    }
+
     if (fromStore) {
       out.push('');
       const note = t.history.storeNoLabels();
@@ -4248,7 +4325,16 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
    * way, because a waived failure that vanished from the output would be a
    * finding deleted with extra steps.
    */
-  const waived = (gate: string): boolean => {
+  /**
+   * Uses recorded this run, flushed after the gates have finished.
+   *
+   * Collected rather than written inline because `waived` is synchronous and
+   * called from seven places inside the gate pass. Writing from each of them
+   * would mean seven awaits threaded through the exit-code logic — the one
+   * part of this command where a mistake turns a red build green.
+   */
+  const waiverUses: WaiverUse[] = [];
+  const waived = (gate: string, measuredUsd: number | null = null, limitUsd: number | null = null): boolean => {
     const found = waiverFor(gate);
     if (found === null) return false;
     if (found.expired) {
@@ -4264,6 +4350,29 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
     console.error(
       c.yellow(t.profile.waiveActive(gate, found.entry.reason, found.entry.until, String(daysLeft))),
     );
+    /**
+     * Recorded **when it silences something**, never when it is configured.
+     *
+     * A waiver nobody's build has ever hit is not a habit — it is dead config
+     * — and the history reports the two apart. This is also the only honest
+     * way to build the record 1.40 refused to invent: it starts today and
+     * says so, rather than reconstructing a past from the present.
+     *
+     * The reason and the expiry are taken from the config **as it stands at
+     * this moment**, because that is the decision that was actually in force.
+     * Reading today's reason back onto last quarter's use is the same mistake
+     * one layer down.
+     */
+    waiverUses.push({
+      schemaVersion: 1,
+      day: waiverDay(new Date()),
+      gate,
+      reason: found.entry.reason,
+      until: found.entry.until,
+      commit: process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? null,
+      measuredUsd,
+      limitUsd,
+    });
     return true;
   };
   const applyGates = (): void => {
@@ -4312,7 +4421,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         }
         if (usd > limit) {
           console.error(c.red(t.profile.labelBudgetFailed(label, formatUsd(usd), formatUsd(limit))));
-          if (!waived(`byLabel:${label}`)) process.exitCode = 1;
+          if (!waived(`byLabel:${label}`, usd, limit)) process.exitCode = 1;
         } else {
           console.error(c.dim(t.profile.labelBudgetOk(label, formatUsd(usd), formatUsd(limit))));
         }
@@ -4385,7 +4494,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
          * copy says so.
          */
         explainFailure(report.total.totalUsd - maxUsd);
-        if (!waived('maxUsd')) process.exitCode = 1;
+        if (!waived('maxUsd', report.total.totalUsd, maxUsd)) process.exitCode = 1;
       } else {
         console.error(c.dim(t.profile.maxUsdOk(formatUsd(report.total.totalUsd), formatUsd(maxUsd))));
         explainMargin(report.total.totalUsd, maxUsd);
@@ -4425,7 +4534,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         process.exitCode = 1;
       } else if (againstDelta > maxGrowth) {
         console.error(c.red(t.profile.maxGrowthUsdFailed(formatSignedUsd(againstDelta), formatUsd(maxGrowth))));
-        if (!waived('maxGrowthUsd')) process.exitCode = 1;
+        if (!waived('maxGrowthUsd', againstDelta, maxGrowth)) process.exitCode = 1;
       }
     }
     /**
@@ -4443,7 +4552,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
         console.error(
           c.red(t.profile.maxCacheLossFailed(formatUsd(gateCache.deltaUsd), formatUsd(maxLoss))),
         );
-        if (!waived('maxCacheLossUsd')) process.exitCode = 1;
+        if (!waived('maxCacheLossUsd', gateCache.deltaUsd, maxLoss)) process.exitCode = 1;
       } else if (gateCache.worstCaseDeltaUsd > maxLoss) {
         console.error(
           c.red(
@@ -4454,7 +4563,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
             ),
           ),
         );
-        if (!waived('maxCacheLossUsd')) process.exitCode = 1;
+        if (!waived('maxCacheLossUsd', gateCache.worstCaseDeltaUsd, maxLoss)) process.exitCode = 1;
       } else {
         console.error(
           c.dim(t.profile.maxCacheLossOk(formatUsd(Math.max(0, gateCache.worstCaseDeltaUsd)), formatUsd(maxLoss))),
@@ -4503,7 +4612,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
             c.red(`${t.profile.maxDayFailed(worst.day, formatUsd(worst.usd), formatUsd(maxDay))}${suspect}`),
           );
           explainFailure(worst.usd - maxDay, { namesLargest: true });
-          if (!waived('maxDayUsd')) process.exitCode = 1;
+          if (!waived('maxDayUsd', worst.usd, maxDay)) process.exitCode = 1;
         } else {
           console.error(c.dim(t.profile.maxDayOk(worst.day, formatUsd(worst.usd), formatUsd(maxDay))));
           explainMargin(worst.usd, maxDay);
@@ -4545,7 +4654,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
           c.red(t.profile.maxSessionFailed(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))),
         );
         explainFailure(report.sessionSpend.maxUsd - maxSession);
-        if (!waived('maxSessionUsd')) process.exitCode = 1;
+        if (!waived('maxSessionUsd', report.sessionSpend.maxUsd, maxSession)) process.exitCode = 1;
       } else {
         console.error(
           c.dim(t.profile.maxSessionOk(formatUsd(report.sessionSpend.maxUsd), formatUsd(maxSession), n(report.sessionSpend.sessions))),
@@ -4579,6 +4688,26 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
     }
   };
 
+  /**
+   * Writes down every waiver that silenced something this run.
+   *
+   * **A failure here never fails the build.** The gate's job is the exit code;
+   * a read-only checkout or a full disk must not turn a passing build red on
+   * account of bookkeeping. The problem is reported and the gate's own verdict
+   * stands — which is also why this runs after `recordGates` rather than
+   * inside it: nothing about the exit code depends on the write.
+   */
+  const recordWaiverUses = async (): Promise<void> => {
+    if (waiverUses.length === 0) return;
+    for (const use of waiverUses) {
+      const failed = await appendWaiverUse('.', use);
+      if (failed !== null) {
+        console.error(c.dim(t.profile.waiveNotRecorded(WAIVER_LOG, failed)));
+        return;
+      }
+    }
+  };
+
   /**
    * The side files the caller asked for. Written on **both** output paths:
    * under --json the human rendering returns early, and the first version of
@@ -4745,6 +4874,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
       ),
     );
     recordGates();
+    await recordWaiverUses();
     await writeSideFiles();
     return;
   }
@@ -5899,6 +6029,7 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
   reportProfileGaps(report, t, n, pricingStale);
 
   recordGates();
+  await recordWaiverUses();
 
   await writeSideFiles();
 }
@@ -7612,7 +7743,7 @@ async function main(): Promise<void> {
       await commandVerify(args, pricing, t);
       break;
     case 'history':
-      await commandHistory(args, pricing, t);
+      await commandHistory(args, config, pricing, t);
       break;
     case 'connect':
       await commandConnect(args, pricing, t);

package/src/waiver-log.ts

@@ -0,0 +1,81 @@
+/**
+ * Where a waiver's uses are written down.
+ *
+ * The core decides what a use means and what a run of them adds up to; this
+ * decides where the bytes go — the same split every module here follows, so
+ * `@trazum/core` stays browser-safe and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, and never rewritten.** There is deliberately no prune, no
+ * compaction and no `--clear`: a record of decisions that the tool can erase
+ * is a record nobody can rely on, and the one thing a waiver history is for is
+ * being awkward six months later. Deleting the file is a thing a person does
+ * with `rm`, on purpose, having seen it.
+ *
+ * **A write that fails never fails the run.** The gate's job is the exit code.
+ * A read-only checkout, a full disk or a directory somebody's CI cannot create
+ * must not turn a passing build red on account of bookkeeping — the failure is
+ * reported and the gate's own verdict stands.
+ *
+ * **A line that will not parse is counted and skipped**, exactly as in the
+ * store. Losing the whole history because one line is broken would be the
+ * worst possible response; pretending the history is complete would be the
+ * second worst.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isWaiverUse } from '@trazum/core';
+import type { WaiverUse } from '@trazum/core';
+
+/** One file, not one per month: a waiver history is small and read whole. */
+export const WAIVER_LOG = '.trazum/waivers.jsonl';
+
+export interface WaiverReadResult {
+  uses: WaiverUse[];
+  /** 1-based positions of lines that would not parse. Named, never dropped quietly. */
+  unreadable: number[];
+  /** False when the file does not exist — "nothing recorded" is not "no file". */
+  present: boolean;
+}
+
+export async function readWaiverLog(root: string): Promise<WaiverReadResult> {
+  let raw: string;
+  try {
+    raw = await readFile(join(root, WAIVER_LOG), 'utf8');
+  } catch {
+    // Absent is the normal state of a repository that has never waived
+    // anything, and it is not an error.
+    return { uses: [], unreadable: [], present: false };
+  }
+
+  const uses: WaiverUse[] = [];
+  const unreadable: number[] = [];
+  raw.split('\n').forEach((line, index) => {
+    if (line.trim() === '') return;
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (isWaiverUse(parsed)) uses.push(parsed);
+      else unreadable.push(index + 1);
+    } catch {
+      unreadable.push(index + 1);
+    }
+  });
+  return { uses, unreadable, present: true };
+}
+
+/**
+ * Appends one use, and swallows any failure after reporting it.
+ *
+ * Returns the error message rather than throwing, so the caller can print it
+ * beside the gate's own output without the gate ever depending on the write.
+ */
+export async function appendWaiverUse(root: string, use: WaiverUse): Promise<string | null> {
+  const path = join(root, WAIVER_LOG);
+  try {
+    await mkdir(join(path, '..'), { recursive: true });
+    await writeFile(path, `${JSON.stringify(use)}\n`, { flag: 'a', mode: 0o600 });
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}