@trazum/cli 1.42.0 → 1.43.0

package/dist/watch-run.d.ts

@@ -0,0 +1,69 @@
+/**
+ * One cycle of watching, and the state that survives a restart.
+ *
+ * `--once` is the primitive: pull the window, keep it, evaluate the gates,
+ * emit what crossed, save state. A cron entry runs exactly that, and so does
+ * every test. The foreground loop is this function in a timer, so there is one
+ * code path and no daemon-only behaviour that nobody exercises.
+ *
+ * **The state file is what makes a restart honest.** Without it a resumed
+ * watcher re-alerts on yesterday's crossing (noise nobody reads) and implies
+ * it was watching the whole time (a claim it cannot make). With it, the
+ * crossing stays quiet and the unwatched stretch gets named once.
+ */
+import type { WatchCrossing } from '@trazum/core';
+export declare const WATCH_STATE_FILE = ".trazum/watch.json";
+export declare const WATCH_STATE_VERSION = 1;
+export interface WatchState {
+    v: number;
+    /** When the last cycle ran, so a long silence can be told from a first run. */
+    lastCycleMs: number;
+    /** How far the measurements reached, for the coverage gap. */
+    lastCoveredToMs: number | null;
+    /** Gate keys already alerted on, so a restart is not amnesia. */
+    fired: Record<string, number>;
+}
+export declare function readWatchState(root: string): Promise<WatchState | null>;
+export declare function writeWatchState(root: string, state: WatchState): Promise<void>;
+/**
+ * Whether a webhook URL is one this tool will post to.
+ *
+ * **This is not the SSRF case and the difference matters.** `checkedEndpoint`
+ * exists because a *request body* must never name a host: an anonymous caller
+ * pointing a shared server at an internal address is somebody else's machine
+ * reaching somewhere it was never meant to. Here the URL is in the operator's
+ * own config, on their own machine, and pointing it at their own alerting
+ * daemon on loopback is the ordinary case rather than the attack.
+ *
+ * So loopback is allowed and plain http is allowed *only* there, while two
+ * rules stay absolute: no credentials embedded in the URL, because a URL ends
+ * up in logs and shell history; and https everywhere else, because an alert
+ * carries spend figures across a network.
+ */
+export type WebhookRejection = 'invalid-url' | 'credentials-in-url' | 'insecure-scheme';
+export declare function checkWebhook(raw: string): {
+    ok: true;
+    url: URL;
+} | {
+    ok: false;
+    reason: WebhookRejection;
+};
+/**
+ * The alert payload.
+ *
+ * Figures and gate names, never prompt text — the store has never held any and
+ * neither does this. Every crossing carries its own provenance, so a receiver
+ * that fans these into a dashboard cannot lose track of what kind of number it
+ * is holding.
+ */
+export interface WatchAlert {
+    schemaVersion: 1;
+    firedAtMs: number;
+    crossings: WatchCrossing[];
+}
+export declare function postWebhook(url: URL, alert: WatchAlert, fetchImpl?: typeof fetch): Promise<{
+    ok: boolean;
+    status: number | null;
+    error: string | null;
+}>;
+//# sourceMappingURL=watch-run.d.ts.map

package/dist/watch-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-run.d.ts","sourceRoot":"","sources":["../src/watch-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAErD,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAU7E;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,oBAAoB,GAAG,iBAAiB,CAAC;AAExF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,GAAG,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAkB1G;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,wBAAsB,WAAW,CAC/B,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,UAAU,EACjB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAmBvE"}

package/dist/watch-run.js

@@ -0,0 +1,79 @@
+/**
+ * One cycle of watching, and the state that survives a restart.
+ *
+ * `--once` is the primitive: pull the window, keep it, evaluate the gates,
+ * emit what crossed, save state. A cron entry runs exactly that, and so does
+ * every test. The foreground loop is this function in a timer, so there is one
+ * code path and no daemon-only behaviour that nobody exercises.
+ *
+ * **The state file is what makes a restart honest.** Without it a resumed
+ * watcher re-alerts on yesterday's crossing (noise nobody reads) and implies
+ * it was watching the whole time (a claim it cannot make). With it, the
+ * crossing stays quiet and the unwatched stretch gets named once.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { SAFE_FETCH_INIT } from '@trazum/core/node';
+export const WATCH_STATE_FILE = '.trazum/watch.json';
+export const WATCH_STATE_VERSION = 1;
+export async function readWatchState(root) {
+    try {
+        const parsed = JSON.parse(await readFile(join(root, WATCH_STATE_FILE), 'utf8'));
+        if (parsed?.v !== WATCH_STATE_VERSION)
+            return null;
+        return parsed;
+    }
+    catch {
+        // No state, or state this version cannot read: a first cycle either way,
+        // which is a state the caller reports rather than an error.
+        return null;
+    }
+}
+export async function writeWatchState(root, state) {
+    const path = join(root, WATCH_STATE_FILE);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+export function checkWebhook(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { ok: false, reason: 'invalid-url' };
+    }
+    if (url.username !== '' || url.password !== '') {
+        return { ok: false, reason: 'credentials-in-url' };
+    }
+    const loopback = url.hostname === 'localhost' ||
+        url.hostname === '127.0.0.1' ||
+        url.hostname === '[::1]' ||
+        url.hostname === '::1';
+    if (url.protocol === 'https:')
+        return { ok: true, url };
+    if (url.protocol === 'http:' && loopback)
+        return { ok: true, url };
+    return { ok: false, reason: 'insecure-scheme' };
+}
+export async function postWebhook(url, alert, fetchImpl = fetch) {
+    try {
+        const response = await fetchImpl(url.toString(), {
+            ...SAFE_FETCH_INIT,
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(alert),
+            signal: AbortSignal.timeout(10_000),
+        });
+        return { ok: response.ok, status: response.status, error: null };
+    }
+    catch (error) {
+        /**
+         * A webhook that will not deliver must not take the alert down with it.
+         * The exit code and the stdout event have already carried the crossing;
+         * losing those because a receiver is down would make the quietest failure
+         * the loudest one.
+         */
+        return { ok: false, status: null, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=watch-run.js.map

package/dist/watch-run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-run.js","sourceRoot":"","sources":["../src/watch-run.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.42.0",
+  "version": "1.43.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.42.0"
+    "@trazum/core": "1.43.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -44,6 +44,7 @@ ${bold('USAGE')}
   trazum history <dir-of-stored-reports> [options]
   trazum connect <anthropic|openai> [options]
   trazum store [--prune] [options]
+  trazum watch [--once | --interval 15m] [options]
   trazum diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -321,6 +322,35 @@ ${bold('OPTIONS FOR plan')}
   a plan that hides its assumptions is advice pretending to be arithmetic.
   Projected savings and money already spent are separate totals throughout.
 
+${bold('OPTIONS FOR watch')}
+  --once                      One cycle: measure, keep, evaluate, emit,
+                              remember. What a cron entry runs. The default.
+  --interval <n>m|h           Stay in the foreground and repeat. Minimum five
+                              minutes: usage APIs are rate limited, and a tight
+                              loop is a way to get your own key throttled.
+  --webhook <url>             POST the crossings somewhere. https only, except
+                              loopback; a URL carrying credentials is refused,
+                              because URLs end up in logs and shell history.
+  --payload <file>            Evaluate a usage payload you already have,
+                              instead of the store.
+  --json                      The cycle as data: crossings, abstentions, gap.
+
+  Evaluates the spend gates from your config — maxUsd, maxDayUsd,
+  maxCacheLossUsd — against what has been measured, and tells you the
+  afternoon it happens rather than three weeks later. Exits 1 when something
+  crossed, so cron mails it and CI fails.
+
+  An alert fires on a measured crossing and never on a projection: "you have
+  spent $412 of a $400 budget" is a fact and "you will exceed" is a forecast,
+  which this tool does not make at any window length. A day still being
+  measured is reported as not yet judgeable rather than passed — but a day
+  already over budget fires whatever the hour, because it does not become less
+  over budget at midnight.
+
+  A restart does not re-alert on a crossing already reported, and names the
+  stretch it was not watching, because a watcher that resumes in silence
+  implies coverage it did not have.
+
 ${bold('OPTIONS FOR store')}
   --prune                     Drop measurements older than the retention
                               policy, and compact the append log to what the
@@ -1506,6 +1536,49 @@ ${bold('EXAMPLES')}
       `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
   },
 
+  watch: {
+    noThresholds: () =>
+      'Watching needs something to watch for. Set spend.maxUsd, spend.maxDayUsd or spend.maxCacheLossUsd in trazum.config.json — a watcher with no threshold is a green light nobody earned.',
+    nothingToWatch: (dir) =>
+      `Nothing has been measured yet: the store at ${dir} is empty. Fill it with "trazum connect <provider> --store" first — watching nothing would report that everything is fine.`,
+    intervalTooTight: () =>
+      '--interval must be at least 5m. Usage APIs are rate limited, and a tight loop is a way to get your own key throttled by a tool that exists to save you money.',
+    badWebhook: (reason) =>
+      reason === 'credentials-in-url'
+        ? 'That webhook URL carries credentials. URLs end up in logs, shell history and error messages, so this one is refused — put the secret in a header your receiver checks, or in the receiver itself.'
+        : reason === 'insecure-scheme'
+          ? 'A webhook must be https, except on loopback. An alert carries your spend figures, and sending them in the clear across a network is a leak you did not ask for.'
+          : 'That webhook is not a URL this tool can parse.',
+    crossed: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'Total spend'
+          : gate === 'maxDayUsd'
+            ? `Spend on ${day}`
+            : 'Money lost to caching';
+      return `CROSSED — ${what} is ${measured} against a limit of ${limit}. Measured, not projected.`;
+    },
+    stillOver: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'Total spend'
+          : gate === 'maxDayUsd'
+            ? `Spend on ${day}`
+            : 'Money lost to caching';
+      return `STILL OVER — ${what} is ${measured} against a limit of ${limit}, and was already reported. Quiet is not clean.`;
+    },
+    notJudgeable: (gate, reason, covered) =>
+      reason === 'window-too-short'
+        ? `${gate} cannot be judged yet: this period is ${covered ?? 'partly'} measured, and a threshold over part of a day is a threshold over something else. Not a pass — it will be judged when the day is in.`
+        : `${gate} cannot be judged on this source, which does not serve what the gate is written against. Not a pass: a gate silently skipped reads exactly like a gate that keeps passing.`,
+    gap: (from, to) =>
+      `Nothing was watching between ${from} and ${to}. Whatever crossed in that stretch was not seen, and this line exists so a resumed watcher does not imply coverage it did not have.`,
+    allWithin: (gates) => `Within every threshold: ${gates} gates evaluated against measured spend.`,
+    webhookFailed: (status) =>
+      `The webhook did not deliver (${status}). The crossing is still in the exit code and in the output above — a receiver being down must not be the quietest failure in the room.`,
+    watching: (minutes) => `Watching every ${minutes} minutes. Ctrl-C stops it.`,
+  },
+
   store: {
     appended: (count, dir) => `Kept ${count} measurements in ${dir}.`,
     empty: (dir) =>

package/src/i18n/es.ts

@@ -31,6 +31,7 @@ ${bold('USO')}
   trazum history <dir-de-informes-guardados> [opciones]
   trazum connect <anthropic|openai> [opciones]
   trazum store [--prune] [opciones]
+  trazum watch [--once | --interval 15m] [opciones]
   trazum diff <antes> <después> [opciones]
   trazum diff --all <dir> <dir> [opciones]
   trazum rank <dir> [opciones]
@@ -328,6 +329,37 @@ ${bold('OPCIONES DE plan')}
   consejo haciéndose pasar por aritmética. El ahorro proyectado y el dinero ya
   gastado son totales separados en todas partes.
 
+${bold('OPCIONES DE watch')}
+  --once                      Una vuelta: medir, guardar, evaluar, emitir,
+                              recordar. Lo que ejecuta una entrada de cron. Es
+                              lo que se hace por defecto.
+  --interval <n>m|h           Se queda en primer plano y repite. Mínimo cinco
+                              minutos: las APIs de uso están limitadas por
+                              tasa, y un bucle apretado es una forma de que te
+                              estrangulen tu propia clave.
+  --webhook <url>             Envía los cruces por POST. Solo https, salvo en
+                              loopback; una URL con credenciales se rechaza,
+                              porque las URLs acaban en logs e historiales.
+  --payload <fichero>         Evalúa un payload de uso que ya tengas, en vez
+                              del almacén.
+  --json                      La vuelta como datos: cruces, abstenciones, hueco.
+
+  Evalúa los gates de gasto de tu configuración — maxUsd, maxDayUsd,
+  maxCacheLossUsd — contra lo que se ha medido, y te lo dice la tarde en que
+  pasa en vez de tres semanas después. Sale con 1 cuando algo cruzó, así que
+  cron te lo manda y CI falla.
+
+  Una alerta salta por un cruce medido y nunca por una proyección: "has
+  gastado $412 de un presupuesto de $400" es un hecho y "vas a excederte" es un
+  pronóstico, que esta herramienta no hace a ninguna escala de ventana. Un día
+  que todavía se está midiendo se reporta como aún no juzgable en vez de
+  aprobarse — pero un día que ya se pasó del presupuesto salta a cualquier
+  hora, porque no se pasa menos a medianoche.
+
+  Un reinicio no vuelve a avisar de un cruce ya reportado, y nombra el tramo
+  que no estuvo vigilando, porque un vigilante que se reanuda en silencio
+  insinúa una cobertura que no tuvo.
+
 ${bold('OPCIONES DE store')}
   --prune                     Borra las mediciones más antiguas que la política
                               de retención y compacta el log a lo que el
@@ -1531,6 +1563,49 @@ ${bold('EJEMPLOS')}
       `Plan escrito en ${path}, con fecha. Guárdalo: una predicción que nadie apuntó es una predicción que no se le puede exigir a nadie.`,
   },
 
+  watch: {
+    noThresholds: () =>
+      'Vigilar necesita algo que vigilar. Define spend.maxUsd, spend.maxDayUsd o spend.maxCacheLossUsd en trazum.config.json — un vigilante sin umbral es una luz verde que nadie se ha ganado.',
+    nothingToWatch: (dir) =>
+      `Todavía no se ha medido nada: el almacén de ${dir} está vacío. Llénalo primero con "trazum connect <proveedor> --store" — vigilar la nada reportaría que todo está bien.`,
+    intervalTooTight: () =>
+      '--interval tiene que ser de al menos 5m. Las APIs de uso están limitadas por tasa, y un bucle apretado es una forma de que una herramienta que existe para ahorrarte dinero acabe estrangulando tu propia clave.',
+    badWebhook: (reason) =>
+      reason === 'credentials-in-url'
+        ? 'Esa URL de webhook lleva credenciales. Las URLs acaban en logs, historiales de shell y mensajes de error, así que se rechaza — pon el secreto en una cabecera que tu receptor compruebe, o en el propio receptor.'
+        : reason === 'insecure-scheme'
+          ? 'Un webhook tiene que ser https, salvo en loopback. Una alerta lleva tus cifras de gasto, y mandarlas en claro por una red es una fuga que no pediste.'
+          : 'Ese webhook no es una URL que esta herramienta pueda parsear.',
+    crossed: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'El gasto total'
+          : gate === 'maxDayUsd'
+            ? `El gasto del ${day}`
+            : 'El dinero perdido con la caché';
+      return `CRUZADO — ${what} es ${measured} contra un límite de ${limit}. Medido, no proyectado.`;
+    },
+    stillOver: (gate, measured, limit, day) => {
+      const what =
+        gate === 'maxUsd'
+          ? 'El gasto total'
+          : gate === 'maxDayUsd'
+            ? `El gasto del ${day}`
+            : 'El dinero perdido con la caché';
+      return `SIGUE POR ENCIMA — ${what} es ${measured} contra un límite de ${limit}, y ya se avisó. Callado no es limpio.`;
+    },
+    notJudgeable: (gate, reason, covered) =>
+      reason === 'window-too-short'
+        ? `${gate} todavía no se puede juzgar: este período está medido al ${covered ?? 'parcialmente'}, y un umbral sobre parte de un día es un umbral sobre otra cosa. No es un aprobado — se juzgará cuando el día esté completo.`
+        : `${gate} no se puede juzgar en esta fuente, que no sirve aquello sobre lo que está escrito el gate. No es un aprobado: un gate saltado en silencio se lee exactamente igual que un gate que lleva tiempo pasando.`,
+    gap: (from, to) =>
+      `Nada estuvo vigilando entre ${from} y ${to}. Lo que cruzara en ese tramo no se vio, y esta línea existe para que un vigilante reanudado no insinúe una cobertura que no tuvo.`,
+    allWithin: (gates) => `Dentro de todos los umbrales: ${gates} gates evaluados contra gasto medido.`,
+    webhookFailed: (status) =>
+      `El webhook no se entregó (${status}). El cruce sigue en el código de salida y en la salida de arriba — que un receptor esté caído no puede ser el fallo más silencioso de la sala.`,
+    watching: (minutes) => `Vigilando cada ${minutes} minutos. Ctrl-C lo para.`,
+  },
+
   store: {
     appended: (count, dir) => `Guardadas ${count} mediciones en ${dir}.`,
     empty: (dir) =>

package/src/i18n/types.ts

@@ -1,4 +1,4 @@
-import type { CannotTellReason, EvalVerdict, Locale, PlanActionKind, PlanAssumption, RuleLevel, VerifyOutcome } from '@trazum/core';
+import type { CannotTellReason, EvalVerdict, Locale, NotJudgeable, PlanActionKind, PlanAssumption, RuleLevel, VerifyOutcome, WatchGate } from '@trazum/core';
 
 /**
  * The CLI's own message catalogue.
@@ -1072,6 +1072,32 @@ export interface CliMessages {
     wrote(path: string): string;
   };
 
+  /**
+   * `trazum watch` — the gates, evaluated as the money moves.
+   *
+   * The copy here carries the rule that makes an alert at 3am trustworthy: a
+   * crossing is measured, never projected, and a period too short to judge is
+   * said to be rather than passed.
+   */
+  watch: {
+    /** Watching with no threshold configured is a green light nobody earned. */
+    noThresholds(): string;
+    nothingToWatch(dir: string): string;
+    intervalTooTight(): string;
+    badWebhook(reason: 'invalid-url' | 'credentials-in-url' | 'insecure-scheme'): string;
+    /** A measured crossing. `day` names the afternoon when the gate is a day gate. */
+    crossed(gate: WatchGate, measured: string, limit: string, day: string | null): string;
+    /** Still over the limit, and already reported — quiet, but not clean. */
+    stillOver(gate: WatchGate, measured: string, limit: string, day: string | null): string;
+    /** Neither a pass nor a failure: this cannot be judged yet, and why. */
+    notJudgeable(gate: WatchGate, reason: NotJudgeable, covered: string | null): string;
+    /** The stretch nobody was watching, named rather than implied away. */
+    gap(from: string, to: string): string;
+    allWithin(gates: string): string;
+    webhookFailed(status: string): string;
+    watching(minutes: string): string;
+  };
+
   /**
    * `trazum store` — the measurements kept on disk.
    *

package/src/index.ts

@@ -20,6 +20,8 @@ import {
   normalizeAnthropicUsage,
   normalizeOpenAIUsage,
   bucketsFromRecords,
+  evaluateWatch,
+  firedKey,
   pruneRecords,
   recordsFromBuckets,
   storeInventory,
@@ -146,6 +148,13 @@ import {
 import type { Revision } from './git.js';
 import { fetchProviderUsage } from './connect.js';
 import { STORE_DIR, appendRecords, readStore, rewriteStore } from './store-fs.js';
+import {
+  WATCH_STATE_VERSION,
+  checkWebhook,
+  postWebhook,
+  readWatchState,
+  writeWatchState,
+} from './watch-run.js';
 import { detectLocale, getCliMessages } from './i18n/index.js';
 import {
   MAX_SUMMARY_CHARS,
@@ -196,6 +205,8 @@ const VALUE_FLAGS = new Set([
   'min-usd',
   'payload',
   'keep',
+  'interval',
+  'webhook',
   // `route` takes a path here, and the flag is deliberately not `--prompt`:
   // everywhere else in this tool `--prompt` names a marked prompt *inside* a
   // source file, and reusing it for a path would be a trap laid for the reader.
@@ -501,6 +512,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   history: ['store', 'json', 'markdown-out'],
   connect: ['since', 'until', 'payload', 'store', 'json', 'out', 'markdown-out', 'pricing', 'pricing-live', 'dry-run'],
   store: ['prune', 'keep', 'json', 'pricing', 'pricing-live', 'dry-run'],
+  watch: ['once', 'interval', 'since', 'payload', 'webhook', 'json', 'pricing', 'pricing-live'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2282,6 +2294,213 @@ function parseWhen(
   throw new Error(t.profile.badWhen(flag, value));
 }
 
+/**
+ * `trazum watch` — the afternoon it happened, said that afternoon.
+ *
+ * One cycle is the primitive: measure, keep, evaluate, emit, remember. The
+ * loop is that cycle in a timer, so a cron entry and a foreground watcher run
+ * exactly the same code and the tests exercise the thing that ships.
+ *
+ * Three transports, all boring on purpose: a non-zero exit code so cron mails
+ * it, a JSON event on stdout so any pipeline can read it, and a webhook for
+ * the operator who already has somewhere for alerts to go. No hosted service
+ * and no account.
+ */
+async function commandWatch(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const root = process.cwd();
+  const asJson = boolFlag(args, 'json');
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+  const day = (msValue: number): string => new Date(msValue).toISOString().slice(0, 10);
+
+  const thresholds = {
+    maxUsd: config.spend?.maxUsd,
+    maxDayUsd: config.spend?.maxDayUsd,
+    maxCacheLossUsd: config.spend?.maxCacheLossUsd,
+  };
+  if (
+    thresholds.maxUsd === undefined &&
+    thresholds.maxDayUsd === undefined &&
+    thresholds.maxCacheLossUsd === undefined
+  ) {
+    throw new Error(t.watch.noThresholds());
+  }
+
+  /**
+   * A webhook is a new outbound surface, so it is checked before anything is
+   * sent: credentials in a URL end up in logs and shell history, and an alert
+   * carrying spend figures over plain http across a network is a leak the
+   * operator did not ask for. Loopback is the exception, because pointing a
+   * watcher at your own alerting daemon is the ordinary case.
+   */
+  const webhookRaw = stringFlag(args, 'webhook');
+  let webhook: URL | null = null;
+  if (webhookRaw !== undefined) {
+    const checked = checkWebhook(webhookRaw);
+    if (!checked.ok) throw new Error(t.watch.badWebhook(checked.reason));
+    webhook = checked.url;
+  }
+
+  const intervalRaw = stringFlag(args, 'interval');
+  const once = boolFlag(args, 'once') || intervalRaw === undefined;
+  let intervalMs = 0;
+  if (!once) {
+    const match = /^(\d+)(m|h)$/.exec(intervalRaw!);
+    const amount = match === null ? NaN : Number(match[1]);
+    intervalMs = match?.[2] === 'h' ? amount * 3_600_000 : amount * 60_000;
+    // Usage APIs are rate limited, and a tight loop is a way to get somebody's
+    // key throttled by a tool that was supposed to save them money.
+    if (!Number.isFinite(intervalMs) || intervalMs < 5 * 60_000) {
+      throw new Error(t.watch.intervalTooTight());
+    }
+  }
+
+  const cycle = async (): Promise<number> => {
+    const state = await readWatchState(root);
+    const nowMs = Date.now();
+
+    /**
+     * Where the measurements come from: a saved payload when one is named
+     * (which is how this is tested and how an air-gapped run works), and the
+     * store otherwise. A cycle that found nothing to measure says so — a
+     * watcher over nothing is a green light nobody earned.
+     */
+    const payloadPath = stringFlag(args, 'payload');
+    let pull;
+    if (payloadPath !== undefined) {
+      pull = normalizeAnthropicUsage(JSON.parse(await readFile(payloadPath, 'utf8')));
+    } else {
+      const { resolved } = await readStore(root);
+      if (resolved.records.length === 0) throw new Error(t.watch.nothingToWatch(STORE_DIR));
+      pull = {
+        provider: 'store',
+        granularity: 'bucketed' as const,
+        buckets: bucketsFromRecords(resolved.records),
+        window: null,
+        gaps: [],
+        unavailable: [],
+      };
+    }
+
+    const report = bucketedProfile(pull, { catalogue: pricing });
+    const cache = bucketedCacheEconomics(report);
+    const result = evaluateWatch({
+      report,
+      thresholds,
+      cacheDeltaUsd: cache.verdict === 'no-cache' ? undefined : cache.deltaUsd,
+      nowMs,
+      lastCoveredToMs: state?.lastCoveredToMs ?? undefined,
+      alreadyFired: new Set(Object.keys(state?.fired ?? {})),
+    });
+
+    if (asJson) {
+      console.log(JSON.stringify({ schemaVersion: 1, firedAtMs: nowMs, ...result }, null, 2));
+    } else {
+      if (result.gap !== null) {
+        console.log(c.yellow(wrap(t.watch.gap(day(result.gap.fromMs), day(result.gap.toMs)), 76, '  ')));
+      }
+      for (const crossing of result.crossings) {
+        console.log(
+          c.red(
+            wrap(
+              t.watch.crossed(
+                crossing.gate,
+                formatUsd(crossing.measuredUsd),
+                formatUsd(crossing.limitUsd),
+                crossing.day,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      for (const abstention of result.abstentions) {
+        console.log(
+          c.dim(
+            wrap(
+              t.watch.notJudgeable(
+                abstention.gate,
+                abstention.reason,
+                abstention.detail === null
+                  ? null
+                  : `${Math.round((abstention.detail.coveredMs / abstention.detail.neededMs) * 100)}%`,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      for (const still of result.suppressed) {
+        console.log(
+          c.yellow(
+            wrap(
+              t.watch.stillOver(
+                still.gate,
+                formatUsd(still.measuredUsd),
+                formatUsd(still.limitUsd),
+                still.day,
+              ),
+              76,
+              '  ',
+            ),
+          ),
+        );
+      }
+      if (
+        result.crossings.length === 0 &&
+        result.suppressed.length === 0 &&
+        result.abstentions.length === 0
+      ) {
+        console.log(c.green(wrap(t.watch.allWithin(n(Object.keys(thresholds).filter((k) => thresholds[k as keyof typeof thresholds] !== undefined).length)), 76, '  ')));
+      }
+    }
+
+    if (webhook !== null && result.crossings.length > 0) {
+      const sent = await postWebhook(webhook, {
+        schemaVersion: 1,
+        firedAtMs: nowMs,
+        crossings: result.crossings,
+      });
+      if (!sent.ok) {
+        // Reported and swallowed: the exit code and the event already carried
+        // the crossing, and losing those because a receiver is down would make
+        // the quietest failure the loudest one.
+        console.error(c.yellow(t.watch.webhookFailed(sent.status === null ? sent.error ?? '' : String(sent.status))));
+      }
+    }
+
+    const fired = { ...(state?.fired ?? {}) };
+    for (const crossing of result.crossings) fired[firedKey(crossing.gate, crossing.day)] = nowMs;
+    await writeWatchState(root, {
+      v: WATCH_STATE_VERSION,
+      lastCycleMs: nowMs,
+      lastCoveredToMs: report.span?.toMs ?? state?.lastCoveredToMs ?? null,
+      fired,
+    });
+
+    return result.crossings.length + result.suppressed.length;
+  };
+
+  const crossed = await cycle();
+  // Still over is still a failure: only the alert was already sent.
+  if (crossed > 0) process.exitCode = 1;
+  if (once) return;
+
+  console.log(c.dim(t.watch.watching(String(Math.round(intervalMs / 60_000)))));
+  // The loop is the cycle in a timer and nothing more, so the primitive above
+  // is the only thing that ever needs testing.
+  for (;;) {
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    await cycle();
+  }
+}
+
 /**
  * `trazum store` — what is kept, and what a prune would take.
  *
@@ -6866,6 +7085,9 @@ async function main(): Promise<void> {
     case 'store':
       await commandStore(args, config, pricing, t);
       break;
+    case 'watch':
+      await commandWatch(args, config, pricing, t);
+      break;
     case 'route':
       await commandRoute(args, pricing, t);
       break;