@agentx-core/security-sdk 0.1.0 → 0.2.0

package/dist/novelty.js

@@ -0,0 +1,581 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOVELTY_FILE = exports.MAX_NOVELTY_SHOWN = void 0;
+exports.computeTotals = computeTotals;
+exports.diffNovelty = diffNovelty;
+exports.mergeMark = mergeMark;
+exports.formatNoveltyItem = formatNoveltyItem;
+exports.formattableItems = formattableItems;
+exports.topNovelty = topNovelty;
+exports.noveltyPath = noveltyPath;
+exports.readNovelty = readNovelty;
+exports.advanceMark = advanceMark;
+exports.sessionNoveltyLine = sessionNoveltyLine;
+exports.renderNovelty = renderNovelty;
+/**
+ * NOVELTY: what changed about this ledger since the reader last looked.
+ *
+ * A port of the novelty reader in `agentx_sdk/db.py` and `agentx_sdk/cli.py`. The record
+ * already answers "what did my agent do". This answers "what is different", which is the
+ * question worth coming back for: we only ever flag a small subset of calls, so a line about a
+ * call we would have stopped cannot be the reason anyone runs `audit` twice.
+ *
+ * It blocks nothing and judges nothing. Every line here is arithmetic over rows the ledger
+ * already holds, so this file adds no new field, no new write on the hot path, and nothing new
+ * that leaves the machine.
+ *
+ * 🔴 THREE DECISIONS THAT LOOK LIKE DETAILS AND ARE NOT. Each is copied from the Python side
+ * with its reason, because each was paid for there:
+ *
+ * 1. THE MARK IS A STORED COPY OF THE TOTALS, NEVER A TIMESTAMP AND NEVER A ROW OFFSET
+ *    (`db.py:2533`). The ledger trims at 30 days or 10,000 rows. A "largest amount yet" read
+ *    back off the ROWS therefore goes DOWN when the big row is trimmed, and the next ordinary
+ *    call gets announced as a new record. A stored mark only ever moves up.
+ *
+ * 2. TWO MARKS, NOT ONE (`cli.py:4355`). The session-end line and `audit` are two screens. With
+ *    one shared mark, whichever printed first ATE the news and the other showed nothing.
+ *
+ * 3. READING NEVER CONSUMES (`cli.py:409`, `cli.py:3077`). `readNovelty` is pure; the mark moves
+ *    only when `advanceMark` is called, after the screen has actually been written. A reader
+ *    whose terminal dies mid-screen otherwise loses that novelty permanently.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const ledger_1 = require("./ledger");
+const shape_1 = require("./shape");
+const report_1 = require("./report");
+/** How many lines one screen prints before it counts the rest. */
+exports.MAX_NOVELTY_SHOWN = 6;
+/**
+ * Plain words for "first call to your ___". Deliberately NOT `SURFACE_LABELS`, which is the
+ * short column spelling (DB, FS): "first call to your DB" reads like a column header, not a
+ * sentence. A class with no word here is DROPPED rather than rendered as a raw enum, which is
+ * also why `other` is absent: "first call to your other" says nothing.
+ */
+const SURFACE_WORDS = {
+    db: "database",
+    filesystem: "filesystem",
+    http: "network",
+    shell: "shell",
+    cloud: "cloud account",
+};
+/**
+ * The separator joining an argument-name COMBINATION into one storable string.
+ *
+ * 🔴 WRITTEN AS AN ESCAPE, NEVER AS THE RAW BYTE. A literal NUL in the source makes git classify
+ * this whole file as BINARY: the branch that added it showed `novelty.ts | Bin 0 -> 18719 bytes`,
+ * so the largest new file in the change was invisible to every diff-based review, to git blame,
+ * and to textual merge. Caught in review, after the file had already been through one.
+ *
+ * NUL and not a space, because it cannot occur inside an argument name, so a combination can
+ * never be split back wrongly.
+ */
+const COMBO_SEP = "\u0000";
+/** How many argument names one line will list before it counts the rest. */
+const MAX_ARGS_SHOWN = 3;
+/**
+ * How long a silence has to be before "first call in N days" is worth printing. TWO days, not
+ * one, and the extra day is the whole point: an agent on a daily schedule leaves a 24-hour gap
+ * every single time, so a one-day threshold prints "first call in 1 day" on every run forever.
+ * At two days the sentence says something a reader did not already know.
+ */
+const MIN_GAP_MS = 2 * 86400000;
+/** Local calendar day, as YYYY-MM-DD. Local, not UTC: "busiest day" means the developer's day. */
+function localDay(ts) {
+    const d = new Date(ts);
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+/**
+ * 🔴 THE ONE RULE EVERY RECURRING SIGNAL GOES THROUGH: a record is news when its HOLDER changes,
+ * never when its VALUE moves. Ported from `agentx_sdk/db.py::_record_changed`, which is where it
+ * was decided; this is the TypeScript entry point so a fourth record cannot get it wrong.
+ *
+ * Three signals here are records rather than firsts: busiest tool, busiest day, biggest burst.
+ * Comparing the VALUE re-announces a record every time it grows, and a still-open day grows all
+ * day. A developer running an agent three times on one Tuesday was told "busiest day yet" three
+ * times with a bigger number each time, and the third of those sessions made two calls. Comparing
+ * the IDENTITY -- which day, which minute, which tool -- says it once, when it is actually news.
+ *
+ * Each signal therefore stores the identity of its record beside the value: `maxDay`,
+ * `maxBurstAt`, and the busiest tool's own name.
+ */
+function recordChanged(nowId, wasId) {
+    return Boolean(nowId) && nowId !== wasId;
+}
+function emptyToolTotals() {
+    return {
+        calls: 0, args: [], combos: [], classes: [], maxAmount: 0,
+        maxDayCalls: 0, maxDay: "", maxBurst: 0, maxBurstAt: "", hours: [], weekend: false, lastTs: 0,
+    };
+}
+/**
+ * Roll the kept rows up into per-tool totals. Pure; takes rows and returns a value.
+ *
+ * ⚠️ THIS IS COMPUTED FROM WHAT THE LEDGER STILL HOLDS, so it can be LOWER than a stored mark
+ * after a trim. That is exactly the case decision 1 exists for, and `diffNovelty` only ever
+ * reports a rise, never a fall.
+ */
+function computeTotals(rows) {
+    const tools = {};
+    const perDay = {};
+    const perMinute = {};
+    for (const r of rows) {
+        const name = r.tool || "(unnamed)";
+        const t = (tools[name] ??= emptyToolTotals());
+        t.calls += 1;
+        const names = [...r.args].sort();
+        for (const a of names)
+            if (!t.args.includes(a))
+                t.args.push(a);
+        // The combination is joined into ONE string so the empty set survives as a real member.
+        // `_dumps_set`'s note on the Python side is about the same hazard from the other direction:
+        // "the call took no arguments" is a fact worth announcing, and a separator-join of an empty
+        // list is indistinguishable from a missing value unless it is stored deliberately.
+        const combo = names.join(COMBO_SEP);
+        if (!t.combos.includes(combo))
+            t.combos.push(combo);
+        if (r.surface && r.surface !== shape_1.CLASS_OTHER && !t.classes.includes(r.surface))
+            t.classes.push(r.surface);
+        if (typeof r.amount === "number" && r.amount > t.maxAmount)
+            t.maxAmount = r.amount;
+        const when = new Date(r.ts);
+        const hour = when.getHours();
+        if (!t.hours.includes(hour))
+            t.hours.push(hour);
+        const dow = when.getDay();
+        if (dow === 0 || dow === 6)
+            t.weekend = true;
+        if (r.ts > t.lastTs)
+            t.lastTs = r.ts;
+        const day = localDay(r.ts);
+        const days = (perDay[name] ??= {});
+        days[day] = (days[day] ?? 0) + 1;
+        const minute = Math.floor(r.ts / 60000);
+        const minutes = (perMinute[name] ??= {});
+        minutes[minute] = (minutes[minute] ?? 0) + 1;
+    }
+    for (const [name, t] of Object.entries(tools)) {
+        for (const [day, n] of Object.entries(perDay[name] ?? {})) {
+            if (n > t.maxDayCalls) {
+                t.maxDayCalls = n;
+                t.maxDay = day;
+            }
+        }
+        for (const [minute, n] of Object.entries(perMinute[name] ?? {})) {
+            if (n > t.maxBurst) {
+                t.maxBurst = n;
+                t.maxBurstAt = minute;
+            }
+        }
+        t.args.sort();
+        t.combos.sort();
+        t.classes.sort();
+        t.hours.sort((a, b) => a - b);
+    }
+    let busiest = "", busiestCalls = 0;
+    for (const [name, t] of Object.entries(tools)) {
+        // Ties keep the name already held, so a stable screen does not flicker between two tools
+        // sitting on the same count.
+        if (t.calls > busiestCalls) {
+            busiest = name;
+            busiestCalls = t.calls;
+        }
+    }
+    return {
+        tools, busiest, busiestCalls,
+        totalCalls: rows.length,
+        distinctTools: Object.keys(tools).length,
+    };
+}
+/**
+ * What is new in `current` that was not in `previous`. Pure.
+ *
+ * 🔴 EVERY COMPARISON IS "HAS THIS RISEN", NEVER "HAS THIS CHANGED". A trim can only make the
+ * computed totals smaller, and a smaller number is not news.
+ */
+function diffNovelty(previous, current, rows = []) {
+    const items = [];
+    const prevTools = previous?.tools ?? {};
+    for (const [name, cur] of Object.entries(current.tools)) {
+        const prev = prevTools[name];
+        if (!prev) {
+            items.push({ kind: "tool", tool: name });
+            // A brand new tool's surface, arguments and hours are not eleven separate pieces of news;
+            // they are what "first time we have seen this tool" already means. Only its surface is
+            // worth naming beside it, because that is the fact the developer cannot infer from a name.
+            for (const c of cur.classes) {
+                if (SURFACE_WORDS[c])
+                    items.push({ kind: "surface", tool: name, detail: c });
+            }
+            continue;
+        }
+        for (const c of cur.classes) {
+            if (!prev.classes.includes(c) && SURFACE_WORDS[c]) {
+                items.push({ kind: "surface", tool: name, detail: c });
+            }
+        }
+        const newArgs = cur.args.filter((a) => !prev.args.includes(a));
+        if (newArgs.length)
+            items.push({ kind: "argument", tool: name, detail: newArgs });
+        // A call that DROPPED an argument it had always carried: `deleteRows` called without
+        // `where` for the first time is the shape worth noticing, and it is not visible from the
+        // argument list growing.
+        for (const combo of cur.combos) {
+            if (prev.combos.includes(combo))
+                continue;
+            const present = new Set(combo ? combo.split(COMBO_SEP) : []);
+            const missing = prev.args.filter((a) => !present.has(a));
+            // Only when the tool had a settled argument list to depart from: on a tool seen once,
+            // every new combination "drops" something and the line is noise.
+            if (missing.length && prev.combos.length === 1) {
+                items.push({ kind: "dropped", tool: name, detail: missing });
+            }
+        }
+        if (cur.maxAmount > prev.maxAmount)
+            items.push({ kind: "amount", tool: name, detail: cur.maxAmount });
+        // Both of these are records, so both go through `recordChanged` rather than comparing the
+        // count. A still-open day whose count keeps rising is the same record, not a new one, and
+        // the previous best named beside it is by construction a DIFFERENT day.
+        if (recordChanged(cur.maxDay, prev.maxDay)) {
+            items.push({ kind: "busiest_day", tool: name, detail: [cur.maxDayCalls, prev.maxDayCalls] });
+        }
+        // Independent of the day, on its own identity. Tying it to the day record instead was tried
+        // and reverted: it silenced a runaway minute on a day that set no record, and silenced it
+        // permanently, because the mark's `maxBurst` rises whether or not the line was ever shown.
+        if (recordChanged(cur.maxBurstAt, prev.maxBurstAt)) {
+            items.push({ kind: "burst", tool: name, detail: cur.maxBurst });
+        }
+    }
+    // 🔴 WHEN THE AGENT RAN IS A FACT ABOUT THE SESSION, SO IT IS DIFFED ONCE, OUTSIDE THE LOOP.
+    // These three used to be pushed per tool while carrying an empty tool name. Three tools first
+    // running at 03:00 on a Saturday produced three byte-identical "first call between 03:00 and
+    // 04:00" lines and three identical "first weekend call" lines, which filled the whole
+    // six-line budget with duplicates, pushed every real item behind "(N more not listed)", and
+    // inflated the session line's count to "9 things changed".
+    //
+    // ⚠️ AND NOT ON A FIRST LOOK, for the same reason a brand-new tool does not get its hours
+    // listed beside it: on a ledger we have never marked, "first call between 10:00 and 11:00" is
+    // not news, it is a restatement of "here is the ledger". The per-tool branch above already
+    // skips these for an unseen tool; without this guard the session-level pass reintroduced them
+    // for every tool at once, and the first-look screen grew two lines nobody needed.
+    if (previous) {
+        const prevHours = new Set(Object.values(prevTools).flatMap((t) => t.hours));
+        const curHours = new Set(Object.values(current.tools).flatMap((t) => t.hours));
+        for (const h of [...curHours].sort((a, b) => a - b)) {
+            if (!prevHours.has(h))
+                items.push({ kind: "hour", tool: "", detail: h });
+        }
+        const prevWeekend = Object.values(prevTools).some((t) => t.weekend);
+        const curWeekend = Object.values(current.tools).some((t) => t.weekend);
+        if (curWeekend && !prevWeekend)
+            items.push({ kind: "weekend", tool: "" });
+    }
+    // 🔴 A GAP IS A SILENCE, NOT A SPAN. This used to be `cur.lastTs - prev.lastTs`, which is the
+    // distance to the MOST RECENT call: an agent that ran every day for four days, read on Monday
+    // and again on Friday, was announced as "first call in 4 days". The silence is the distance
+    // from the last call the mark saw to the FIRST call after it, which needs the rows, not the
+    // totals. With no rows passed (a caller diffing two stored marks) the gap is simply not
+    // claimed, rather than claimed wrongly.
+    const prevLast = Math.max(0, ...Object.values(prevTools).map((t) => t.lastTs));
+    if (prevLast && rows.length) {
+        const next = rows.filter((r) => r.ts > prevLast).sort((a, b) => a.ts - b.ts)[0];
+        if (next && next.ts - prevLast >= MIN_GAP_MS) {
+            items.push({ kind: "gap", tool: "", detail: next.ts - prevLast });
+        }
+    }
+    // Through the same rule as the other two records, though this one already compared the tool's
+    // NAME rather than its call count. Routed here so the three cannot drift apart again, which is
+    // what the Python entry point exists to prevent.
+    if (previous?.busiest && recordChanged(current.busiest, previous.busiest)) {
+        items.push({ kind: "busiest", tool: current.busiest });
+    }
+    return items;
+}
+/**
+ * The stored mark, RATCHETED: every maximum and every set only ever grows.
+ *
+ * 🔴 WITHOUT THIS, DECISION 1 AT THE TOP OF THIS FILE IS A COMMENT AND NOT A BEHAVIOUR.
+ * `diffNovelty` only ever reports a rise, but `advanceMark` used to store the freshly computed
+ * totals wholesale, and those are computed over the KEPT rows. So a trim moved the mark DOWN.
+ * Concretely: `chargeCard` runs at 1,000,000 and the mark records it; thirty-one days later that
+ * row is trimmed and the next read stores `maxAmount: 500`; a later call at 900 is then
+ * announced as "largest amount yet: ≥900". The same held for the surface set (a repeat "first
+ * call to your database"), the argument names, the busiest day and the burst.
+ *
+ * `busiest` is deliberately NOT ratcheted: "now your busiest tool" is a claim about the present,
+ * and a genuine change of leader is news each time it happens.
+ *
+ * ⚠️ AND IT IS UNBOUNDED, WHICH IS A KNOWN, DELIBERATE, WRITTEN-DOWN GAP. Before the ratchet the
+ * mark was recomputed from the kept rows, so the ledger's retention capped it as a side effect
+ * nobody had decided; merging removed that cap. A program naming tools dynamically, one per
+ * tenant or per resource, accumulates every name it has ever used.
+ *
+ * 🔴 AN EVICTION RULE WAS WRITTEN AND THEN REVERTED, AND THE REASON IS THE POINT. Dropping tools
+ * whose last call had aged out of the ledger reintroduced this function's own worked example: a
+ * `chargeCard` that runs monthly at 1,000,000 had its entry evicted on day 31 and, on day 32,
+ * was announced as "first time we have seen this tool" with "largest amount yet: ≥900". The
+ * justification, that a tool aged out of the ledger cannot be diffed anyway, was false: the
+ * STORED MARK is the other side of the diff, which is the entire reason totals are stored rather
+ * than read back off the rows. Any eviction keyed on time has this defect for any tool that runs
+ * less often than the window. A cap on the NUMBER of entries would not, and that is what the
+ * backlog row asks for. Growth is slow and hypothetical; the bug the eviction caused was
+ * immediate, so the gap is carried openly instead.
+ */
+function mergeMark(previous, current) {
+    if (!previous)
+        return current;
+    const union = (a, b) => [...new Set([...a, ...b])].sort();
+    const tools = { ...previous.tools };
+    for (const [name, cur] of Object.entries(current.tools)) {
+        const prev = tools[name];
+        if (!prev) {
+            tools[name] = cur;
+            continue;
+        }
+        tools[name] = {
+            calls: Math.max(prev.calls, cur.calls),
+            args: union(prev.args, cur.args),
+            combos: union(prev.combos, cur.combos),
+            classes: union(prev.classes, cur.classes),
+            maxAmount: Math.max(prev.maxAmount, cur.maxAmount),
+            maxDayCalls: Math.max(prev.maxDayCalls, cur.maxDayCalls),
+            maxDay: cur.maxDayCalls > prev.maxDayCalls ? cur.maxDay : prev.maxDay,
+            maxBurst: Math.max(prev.maxBurst, cur.maxBurst),
+            maxBurstAt: cur.maxBurst > prev.maxBurst ? cur.maxBurstAt : prev.maxBurstAt,
+            hours: union(prev.hours, cur.hours).sort((a, b) => a - b),
+            weekend: prev.weekend || cur.weekend,
+            lastTs: Math.max(prev.lastTs, cur.lastTs),
+        };
+    }
+    return {
+        tools,
+        busiest: current.busiest || previous.busiest,
+        busiestCalls: Math.max(previous.busiestCalls, current.busiestCalls),
+        totalCalls: Math.max(previous.totalCalls, current.totalCalls),
+        distinctTools: Object.keys(tools).length,
+    };
+}
+/** The words for one item, in ONE place because two screens print them. "" for anything unrecognised. */
+function formatNoveltyItem(item) {
+    const names = (v) => (Array.isArray(v) ? v.map(String) : []);
+    switch (item.kind) {
+        case "tool":
+            return "first time we have seen this tool";
+        case "surface": {
+            const word = SURFACE_WORDS[item.detail];
+            return word ? `first call to your ${word}` : "";
+        }
+        case "argument": {
+            const n = names(item.detail);
+            if (!n.length)
+                return "";
+            const shown = n.slice(0, MAX_ARGS_SHOWN).join(", ");
+            const rest = n.length - Math.min(n.length, MAX_ARGS_SHOWN);
+            return `called with ${shown}${rest > 0 ? ` and ${rest} more` : ""} for the first time`;
+        }
+        case "dropped": {
+            const n = names(item.detail);
+            if (!n.length)
+                return "";
+            return `called without ${n.slice(0, MAX_ARGS_SHOWN).join(", ")} for the first time`;
+        }
+        case "amount": {
+            // "amount", not "number": the column holds the magnitude of an argument the tool itself
+            // NAMED as an amount. And "yet", because the stored band is a lower bound.
+            const v = Number(item.detail ?? 0);
+            if (!Number.isFinite(v) || v <= 0)
+                return "";
+            return `largest amount yet: ≥${Math.trunc(v).toLocaleString("en-US")}`;
+        }
+        case "busiest":
+            return "now your busiest tool";
+        case "busiest_day": {
+            const pair = Array.isArray(item.detail) ? item.detail : [];
+            const now = Number(pair[0] ?? 0);
+            const before = Number(pair[1] ?? 0);
+            if (!Number.isFinite(now) || now <= 0)
+                return "";
+            // The previous record is stated beside the new one: "45 calls" alone is a number the
+            // reader would have had to be keeping track of to find interesting.
+            // The previous best is honest here because the item only exists when the record changed
+            // HANDS, so the day it names is always a different one. `recordChanged` is what makes that
+            // true; without it this clause described a day that never existed.
+            const head = `busiest day yet: ${(0, report_1.plural)(now, "call")}`;
+            return before ? `${head} (previous best ${before})` : head;
+        }
+        case "burst": {
+            const v = Number(item.detail ?? 0);
+            return v > 0 ? `${(0, report_1.plural)(v, "call")} in one minute, the most yet` : "";
+        }
+        case "hour": {
+            const h = Number(item.detail);
+            if (!Number.isInteger(h))
+                return "";
+            const p = (n) => String(n).padStart(2, "0");
+            // % 24 so the last hour of the day does not render "between 23:00 and 24:00", which is
+            // not a time anybody writes.
+            return `first call between ${p(h)}:00 and ${p((h + 1) % 24)}:00`;
+        }
+        case "weekend":
+            return "first weekend call";
+        case "gap": {
+            const days = Math.floor(Number(item.detail ?? 0) / 86400000);
+            return days >= 1 ? `first call in ${(0, report_1.plural)(days, "day")}` : "";
+        }
+        default:
+            return "";
+    }
+}
+/** Most interesting first. A brand new tool outranks a new hour-of-day on the same screen. */
+const KIND_RANK = {
+    tool: 0, surface: 1, amount: 2, busiest: 3, busiest_day: 4,
+    burst: 5, gap: 6, dropped: 7, argument: 8, weekend: 9, hour: 10,
+};
+/**
+ * The items that actually produce a line. `formatNoveltyItem` returns "" for a kind it cannot
+ * word (a surface with no plain noun, an empty argument list), so a raw `items.length` counts
+ * things no reader will ever see. Both screens count off THIS, so the session line's number and
+ * the report's "(N more not listed)" cannot disagree.
+ */
+function formattableItems(items) {
+    return items.filter((item) => formatNoveltyItem(item) !== "");
+}
+function topNovelty(items, limit) {
+    return [...items]
+        .sort((a, b) => KIND_RANK[a.kind] - KIND_RANK[b.kind] || a.tool.localeCompare(b.tool))
+        .slice(0, Math.max(0, limit));
+}
+// ---------------------------------------------------------------------------
+// The store.
+// ---------------------------------------------------------------------------
+exports.NOVELTY_FILE = ".agentx-novelty.json";
+/** Beside the ledger, so moving the ledger moves the mark with it. */
+function noveltyPath(env = process.env) {
+    return path.join(path.dirname((0, ledger_1.ledgerPath)(env)), exports.NOVELTY_FILE);
+}
+function loadMarkFile(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        // Missing, unreadable or corrupt all mean the same thing to a reader: we have no mark, so
+        // this is a first look. Never throws; novelty is a nicety and must not break `audit`.
+        return {};
+    }
+}
+function saveMarkFile(state, file) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(state), "utf8");
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        /* a mark we could not store means the same novelty is offered again next time */
+    }
+}
+/**
+ * PURE READ. Works out what is new for one screen and stores nothing. `advanceMark` is the
+ * separate, deliberate second step. See decision 3.
+ */
+function readNovelty(mark, rows, file = noveltyPath()) {
+    const current = computeTotals(rows);
+    const previous = loadMarkFile(file).marks?.[mark] ?? null;
+    // Rows are passed through so the gap can be measured as a SILENCE. See the note in diffNovelty.
+    return { items: diffNovelty(previous, current, rows), firstLook: previous === null, current };
+}
+/**
+ * Store the totals for one screen. Called only after the screen has actually been written.
+ *
+ * 🔴 MERGED INTO THE STORED MARK, NEVER WRITTEN OVER IT. `current` is computed from the rows the
+ * ledger still holds, so writing it wholesale moves the mark DOWN after a trim and re-announces
+ * an ordinary call as a record. See `mergeMark`.
+ */
+function advanceMark(mark, current, file = noveltyPath()) {
+    const state = loadMarkFile(file);
+    const previous = state.marks?.[mark] ?? null;
+    state.marks = { ...(state.marks ?? {}), [mark]: mergeMark(previous, current) };
+    saveMarkFile(state, file);
+}
+/**
+ * The ONE line the session-end screen prints: how much is new, and where to read it. "" when
+ * there is nothing to say, so the caller cannot print a bare pointer to an empty report.
+ *
+ * A pure function on purpose. It runs from a process exit hook, where a test cannot see it, and
+ * a sentence is exactly the thing no test reddens unless it is reachable. This one is.
+ */
+function sessionNoveltyLine(read) {
+    const n = formattableItems(read.items).length;
+    if (!n)
+        return "";
+    // 🔴 THE PRONOUN COUNTS TOO. The number went through `plural` and "them" did not, so one item
+    // printed "1 thing changed since you last looked. That report names them." It read as a typo
+    // in the first sentence a developer sees. It was almost never visible while a still-open day
+    // re-announced itself every run and the count was always several; fixing that made n = 1 the
+    // ordinary case, which is how a latent sentence became the common one. Found in a founder walk.
+    const names = n === 1 ? "That report names it." : "That report names them.";
+    return read.firstLook
+        ? ` First look at this ledger: ${(0, report_1.plural)(n, "thing")} to see. ${names}`
+        : ` ${(0, report_1.plural)(n, "thing")} changed since you last looked. ${names}`;
+}
+/**
+ * The block both screens print, as lines. Empty array when there is nothing to say, so a caller
+ * cannot accidentally print a bare header over nothing.
+ *
+ * TWO HEADERS, because they are two different claims. On a ledger we have never marked, every
+ * tool in it is new to US, not new to the agent, and "first call to your database" under a
+ * "since you last looked" header would date a year of history to this afternoon.
+ */
+function renderNovelty(read, indent = "  ") {
+    const all = formattableItems(read.items);
+    const shown = topNovelty(all, exports.MAX_NOVELTY_SHOWN)
+        .map((item) => ({ item, line: formatNoveltyItem(item) }));
+    if (!shown.length)
+        return [];
+    const out = [indent + (read.firstLook ? "FIRST LOOK AT THIS LEDGER" : "NEW SINCE YOU LAST LOOKED")];
+    for (const { item, line } of shown) {
+        // A blank tool name does NOT get the empty column. Padding it printed a sentence marooned a
+        // third of the way across the screen with nothing to its left; the column exists to line
+        // tool names up with each other, and a line with no tool name is not in that column.
+        out.push(item.tool ? `${indent}  ${item.tool.padEnd(24)} ${line}` : `${indent}  ${line}`);
+    }
+    const hidden = all.length - shown.length;
+    if (hidden > 0)
+        out.push(`${indent}  (${hidden} more not listed)`);
+    return out;
+}

package/dist/report.d.ts

@@ -60,8 +60,14 @@ export interface ToolSummary {
 }
 /** Group the rows by tool, busiest first. */
 export declare function summariseTools(rows: readonly CallRow[]): ToolSummary[];
-/** The grouped screen. Returns the text; the caller prints it. */
-export declare function renderTools(read: LedgerRead, opts?: ViewOptions): string;
+/**
+ * The grouped screen. Returns the text; the caller prints it.
+ *
+ * `novelty` is the already-rendered "what changed" block, passed IN rather than computed here.
+ * This module stays a pure formatter: reading the stored mark and moving it are side effects,
+ * and they belong with the caller that also decides whether a human is looking.
+ */
+export declare function renderTools(read: LedgerRead, opts?: ViewOptions, novelty?: readonly string[]): string;
 /** The `--calls` screen: one line per call, newest first. The ORDER is the point. */
 export declare function renderCalls(read: LedgerRead, opts?: ViewOptions): string;
 /**