hippo-memory 1.52.8 → 1.53.0

package/dist/shared.js

@@ -6,16 +6,18 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { generateId } from './memory.js';
+import { generateId, COMPACTION_MEMORY_TAG } from './memory.js';
+import { AGENT_MEMORY_SOURCE_PREFIX, AGENT_MEMORY_TAGS } from './agent-memories/tools.js';
 import { initStore, loadAllEntries, loadIndex, loadSearchEntries, loadRecallSearchEntries, writeEntry, readEntry, } from './store.js';
 import { passesScopeFilterForRecall, passesCliRecallScopeFilter } from './recall-scope.js';
-import { search, hybridSearch } from './search.js';
+import { search, hybridSearch, fitBudget } from './search.js';
 import { evalNow } from './ablation.js';
 import { deriveOriginProject, classifyOriginProject, resolveGlobalRootDir } from './project-identity.js';
 import { detectSecret } from './secret-detect.js';
 import { isQuarantineScope } from './quarantine.js';
 import { RejectedValueError } from './rejection.js';
 import { embedMemory, embedAll } from './embeddings.js';
+import { duplicateKey, storedTextKeys } from './same-text.js';
 /**
  * Returns the path to the global Hippo store.
  * Resolution order: $HIPPO_HOME > $XDG_DATA_HOME/hippo > ~/.hippo/
@@ -70,11 +72,8 @@ export function promoteToGlobal(localRoot, id, opts) {
         origin_project: entry.origin_project ?? deriveOriginProject(path.dirname(path.resolve(localRoot))),
     };
     writeEntry(globalRoot, globalEntry, { actor: opts?.actor });
-    // Fire-and-forget: embedMemory's own availability gate (embeddings.ts:438)
-    // already no-ops when embeddings are unavailable/disabled, so a pre-guard
-    // here would be redundant (capture.ts:598 pre-guards instead; both
-    // contracts are correct, see docs/plans/2026-07-18-global-row-embeddings.md).
-    void embedMemory(globalRoot, globalEntry).catch(() => { });
+    // Fire-and-forget: embedMemory gates on availability and never rejects.
+    void embedMemory(globalRoot, globalEntry);
     return globalEntry;
 }
 /**
@@ -108,7 +107,7 @@ export function searchBoth(query, localRoot, globalRoot, options = {}) {
     // Remove duplicates by content (local/global IDs differ after promote/share)
     const seen = new Set();
     const deduped = tagged.filter((r) => {
-        const key = r.entry.content.slice(0, 200).toLowerCase();
+        const key = duplicateKey(r.entry.content);
         if (seen.has(key))
             return false;
         seen.add(key);
@@ -136,7 +135,7 @@ export function searchBoth(query, localRoot, globalRoot, options = {}) {
  * Async version of searchBoth that calls hybridSearch instead of search.
  */
 export async function searchBothHybrid(query, localRoot, globalRoot, options = {}) {
-    const { budget = 4000, now = evalNow(), embeddingWeight, explain, mmr, mmrLambda, localBump = 1.2, minResults, scope, includeSuperseded, asOf, tenantId, summaryDeboost, summaryFreshness, entryFilter, recallScope } = options;
+    const { budget = 4000, now = evalNow(), embeddingWeight, explain, mmr, mmrLambda, localBump = 1.2, minResults, cost, scope, includeSuperseded, asOf, tenantId, summaryDeboost, summaryFreshness, entryFilter, recallScope } = options;
     // When an admission filter is active, lift the per-store candidate cap
     // (default 200): excluded rows matching the query could otherwise fill the
     // window before any admitted row is even loaded (codex gating round 6).
@@ -177,10 +176,10 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
     if (localEntries.length === 0 && globalEntries.length === 0)
         return [];
     const localResults = await hybridSearch(query, localEntries, {
-        budget, now, hippoRoot: localRoot, embeddingWeight, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness,
+        budget, now, hippoRoot: localRoot, embeddingWeight, explain, mmr, mmrLambda, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness,
     });
     const globalResults = await hybridSearch(query, globalEntries, {
-        budget, now, hippoRoot: globalRoot, embeddingWeight, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness,
+        budget, now, hippoRoot: globalRoot, embeddingWeight, explain, mmr, mmrLambda, minResults, cost, scope, includeSuperseded, asOf, summaryDeboost, summaryFreshness,
     });
     // Tag global results. Local memories get a configurable priority bump.
     const tagged = [
@@ -197,7 +196,7 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
     // Remove duplicates by content (local/global IDs differ after promote/share)
     const seen = new Set();
     const deduped = tagged.filter((r) => {
-        const key = r.entry.content.slice(0, 200).toLowerCase();
+        const key = duplicateKey(r.entry.content);
         if (seen.has(key))
             return false;
         seen.add(key);
@@ -206,17 +205,7 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
     // T2 note: PLAIN stable score sort on purpose -- see searchBoth above;
     // same rationale (deterministic inputs + stability; local-first on ties).
     deduped.sort((a, b) => b.score - a.score);
-    // Apply combined token budget (guarantee at least minResults items)
-    const effectiveMinHybrid = minResults ?? 1;
-    const results = [];
-    let usedTokens = 0;
-    for (let i = 0; i < deduped.length; i++) {
-        if (results.length >= effectiveMinHybrid && usedTokens + deduped[i].tokens > budget)
-            continue;
-        usedTokens += deduped[i].tokens;
-        results.push(deduped[i]);
-    }
-    return results;
+    return fitBudget(deduped, budget, minResults ?? 1, cost);
 }
 // ---------------------------------------------------------------------------
 // Multi-agent shared memory
@@ -232,6 +221,22 @@ const TRANSFERABLE_TAGS = new Set([
     'powershell', 'quant', 'backtest', 'pattern', 'rule', 'gotcha',
     'sub-agent', 'review', 'best-practice',
 ]);
+/** Tags whose rows only a hand-run share or promote may copy to the global store; derived rows inherit them. */
+export const NEVER_AUTO_SHARE_TAGS = new Set([
+    'git-learned',
+    'session-digest',
+    ...AGENT_MEMORY_TAGS,
+]);
+export function neverAutoShareTags(sources) {
+    return [...NEVER_AUTO_SHARE_TAGS].filter((tag) => sources.some((s) => s.tags.includes(tag)));
+}
+/** Tags whose rows sleep keeps as written: never merged, never sent to LLM extraction. Conflict detection keeps its own list. */
+export const NO_MERGE_TAGS = new Set([
+    'extracted',
+    'session-digest',
+    COMPACTION_MEMORY_TAG,
+    ...AGENT_MEMORY_TAGS,
+]);
 /**
  * Estimate how well a memory would transfer to other projects.
  * Returns 0..1 where >0.5 = good candidate for sharing.
@@ -301,10 +306,9 @@ export function shareMemory(localRoot, id, options = {}) {
     // Single-row producer: embed here unless the caller opts out. autoShare
     // sets skipEmbed so it can batch its whole run through one embedAll() at
     // the end instead of N serialized full-index rewrites (embedMemory rewrites
-    // the whole index JSON per call). Same redundant-pre-guard reasoning as
-    // promoteToGlobal above.
+    // the whole index JSON per call).
     if (!options.skipEmbed) {
-        void embedMemory(globalRoot, globalEntry).catch(() => { });
+        void embedMemory(globalRoot, globalEntry);
     }
     return globalEntry;
 }
@@ -358,7 +362,7 @@ export function listPeers(globalRoot, tenantId) {
         .sort((a, b) => b.count - a.count);
 }
 /**
- * Auto-share: find local memories with high transfer scores that aren't already global.
+ * Auto-share: local memories with high transfer scores, not already global, no NEVER_AUTO_SHARE_TAGS tag.
  * Returns the list of shared entries.
  *
  * L9: `options.tenantId` is opt-in. When provided, the LOCAL-entries read is
@@ -392,17 +396,22 @@ export function autoShare(localRoot, options = {}) {
     // per-tenant filtering on the global root would defeat the purpose.
     const globalEntries = loadAllEntries(globalRoot);
     // Build set of global content hashes to avoid duplicates
-    const globalContentSet = new Set(globalEntries.map((e) => e.content.toLowerCase().trim().slice(0, 200)));
+    const globalContentSet = storedTextKeys(globalEntries);
     const candidates = localEntries.filter((entry) => {
         // CD5: shareMemory refuses quarantined rows; filtering here keeps sleep from aborting on one.
         if (isQuarantineScope(entry.scope ?? null))
             return false;
+        // Before the score: these rows describe one project only, and a git seed's 'error' tag clears the bar.
+        if (entry.tags.some((t) => NEVER_AUTO_SHARE_TAGS.has(t)) || entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX)) {
+            if (options.stats)
+                options.stats.neverAutoShareSkipped = (options.stats.neverAutoShareSkipped ?? 0) + 1;
+            return false;
+        }
         const score = transferScore(entry);
         if (score < minScore)
             return false;
-        // Skip if already shared (approximate content match)
-        const contentKey = entry.content.toLowerCase().trim().slice(0, 200);
-        if (globalContentSet.has(contentKey))
+        // Skip if already shared (same text apart from spacing)
+        if (globalContentSet.has(duplicateKey(entry.content)))
             return false;
         // v39 S4 producer veto: secret rows never auto-share, regardless of
         // transfer score. (shareMemory would throw; filtering here keeps the
@@ -476,16 +485,15 @@ export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
     // only stamps when the field is missing).
     const currentName = deriveOriginProject(path.dirname(path.resolve(localRoot)));
     let count = 0;
-    // AT1 (plan §3 containment, the roadmap threat this whole feature targets
-    // — a locally-rejected value must not silently resurrect via sync down
-    // from global): per-item catch, no signature change (bare number return;
-    // see the syncGlobalToLocal callers in cli.ts + tests). Counted locally
-    // and printed as one summary line, same pattern as learnFromMemoryMd.
+    // A locally rejected value must not come back through sync down: caught per item, printed as one line.
     let rejected = 0;
     for (const entry of globalEntries) {
         // Skip if already present by ID
         if (localIndex.entries[entry.id])
             continue;
+        // Only the global store's user pass sets an imported note's row aside, so a copy would outlive the note.
+        if (entry.source.startsWith(AGENT_MEMORY_SOURCE_PREFIX))
+            continue;
         if (localText.has(textKey(entry)))
             continue;
         if (detectSecret(entry).flagged)

package/dist/store.d.ts

@@ -367,7 +367,7 @@ export declare function loadChildrenOf(hippoRoot: string, parentId: string, tena
  * Default keeps `deleteEntry` byte-identical to its pre-split behavior.
  *
  * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
- * existed or `automatic` refused it (pinned or raw at DELETE time, so a late pin wins).
+ * existed or `automatic` refused it (pinned, raw or kept for good at DELETE time, so a late pin wins).
  */
 export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id: string, opts?: {
     actor?: string;
@@ -400,7 +400,7 @@ export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
  *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
  *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
  *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
- *  (pinned or raw since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+ *  (pinned, raw or kept for good since the caller decided). Returns the ids that left `memories`, deleted or moved. */
 export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[], opts?: {
     snapshot?: ReadonlyMap<string, MemoryEntry>;
     dormant?: DormantMove[];
@@ -415,6 +415,12 @@ export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEn
 export declare function loadAllEntries(hippoRoot: string, tenantId?: string): MemoryEntry[];
 /** Every memory row on an open connection, so a caller can read inside its own transaction. */
 export declare function selectAllEntries(db: DatabaseSyncLike, tenantId?: string): MemoryEntry[];
+/** Live rows whose source starts with `prefix`, on the caller's handle; LIKE folds case, so the prefix is checked again exactly. */
+export declare function selectLiveEntriesBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): MemoryEntry[];
+/** Rewrites a live row's tags and its full-text row on the caller's transaction, with no audit row. */
+export declare function setEntryTagsInTx(db: DatabaseSyncLike, entry: MemoryEntry): void;
+/** Removes a row from `memories` and full-text search on the caller's transaction, as sleep's dormant move does, and marks its summary parent dirty. */
+export declare function deleteEntryRowInTx(db: DatabaseSyncLike, entry: MemoryEntry, actor: string): void;
 export declare function loadContentsWithTag(hippoRoot: string, tenantId: string, tag: string): string[];
 export interface AmbientRecallRequest {
     terms: string[];
@@ -645,6 +651,7 @@ export declare function loadLatestHandoff(hippoRoot: string, tenantId: string, s
     unfinishedOnly?: boolean;
     maxAgeMs?: number;
     scopeFilter?: 'default-deny';
+    excludeSessionId?: string;
 }): SessionHandoff | null;
 /**
  * Load a specific handoff by its row ID.

package/dist/store.js

@@ -1555,7 +1555,7 @@ export function loadChildrenOf(hippoRoot, parentId, tenantId) {
  * Default keeps `deleteEntry` byte-identical to its pre-split behavior.
  *
  * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
- * existed or `automatic` refused it (pinned or raw at DELETE time, so a late pin wins).
+ * existed or `automatic` refused it (pinned, raw or kept for good at DELETE time, so a late pin wins).
  */
 export function deleteEntryCore(db, id, opts) {
     // SAFETY: row's shape matches the three columns named in the SELECT above.
@@ -1622,7 +1622,7 @@ function mergeOwnChanges(base, ours, live) {
  *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
  *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
  *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
- *  (pinned or raw since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+ *  (pinned, raw or kept for good since the caller decided). Returns the ids that left `memories`, deleted or moved. */
 export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
     const dormantMoves = opts?.dormant ?? [];
     if (toWrite.length === 0 && toDeleteIds.length === 0 && dormantMoves.length === 0)
@@ -1810,6 +1810,25 @@ export function selectAllEntries(db, tenantId) {
         : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
     return rows.map(rowToEntry);
 }
+/** Live rows whose source starts with `prefix`, on the caller's handle; LIKE folds case, so the prefix is checked again exactly. */
+export function selectLiveEntriesBySourcePrefix(db, tenantId, prefix) {
+    // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+    const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE tenant_id = ? AND superseded_by IS NULL AND source LIKE ? ESCAPE '\\'`).all(tenantId, `${prefix.replace(/[%_\\]/g, '\\$&')}%`);
+    return rows.map(rowToEntry).filter((entry) => entry.source.startsWith(prefix));
+}
+/** Rewrites a live row's tags and its full-text row on the caller's transaction, with no audit row. */
+export function setEntryTagsInTx(db, entry) {
+    db.prepare(`UPDATE memories SET tags_json = ?, updated_at = datetime('now') WHERE id = ? AND tenant_id = ?`)
+        .run(JSON.stringify(entry.tags), entry.id, entry.tenantId);
+    syncFtsRow(db, entry);
+}
+/** Removes a row from `memories` and full-text search on the caller's transaction, as sleep's dormant move does, and marks its summary parent dirty. */
+export function deleteEntryRowInTx(db, entry, actor) {
+    db.prepare('DELETE FROM memories WHERE id = ? AND tenant_id = ?').run(entry.id, entry.tenantId);
+    deleteFtsRow(db, entry.id);
+    if (entry.dag_parent_id)
+        markSummaryDirtyInTx(db, entry.dag_parent_id, entry.tenantId, actor);
+}
 // Content of every tenant row tagged `tag`, without reading the rest of the store.
 // `instr` is a substring prefilter over the raw JSON; `includes` below re-checks exactly.
 export function loadContentsWithTag(hippoRoot, tenantId, tag) {
@@ -2835,6 +2854,10 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}) {
             conditions.push('session_id = ?');
             params.push(sessionId);
         }
+        if (opts.excludeSessionId) {
+            conditions.push('session_id != ?');
+            params.push(opts.excludeSessionId);
+        }
         if (opts.unfinishedOnly) {
             // codex P2: restrict to each session's newest revision first — stampHandoffOutcome
             // only stamps the newest row, so an older null-outcome revision must not resurrect.

package/dist/token-ledger.d.ts

@@ -3,20 +3,24 @@ import type { DatabaseSyncLike } from './db.js';
  * Where a block of memory text was sent.
  * - `hook`: the per-prompt `UserPromptSubmit` hook (`hippo context --pinned-only`).
  * - `hook_recall`: the same hook's Z1 prompt-recall section (docs/plans/2026-09-26-z1-prompt-recall.md).
+ * - `compact_resume`: the snapshot the SessionStart(compact) hook prints (`hippo compact-resume`).
  * - `context`, `recall`: the CLI commands.
  * - `mcp_recall`, `mcp_context`: the MCP tools.
  * - `http_recall`, `http_context`, `http_assemble`: the HTTP API.
  */
-export type TokenSurface = 'hook' | 'hook_recall' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble';
+export type TokenSurface = 'hook' | 'hook_recall' | 'compact_resume' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble';
 /** All surfaces, in report order. */
 export declare const TOKEN_SURFACES: readonly TokenSurface[];
+/** Surfaces whose re-reads are counted: only a hook payload tells a sub-agent's block from its parent's, as both carry one session id. */
+export declare const REREAD_SURFACES: readonly TokenSurface[];
 /**
  * What happened to a block.
  * - `inject`: sent to the agent.
  * - `skip`: identical to the session's last injected block, so not sent again.
  * - `reset`: the host compacted its context, so the next block must be sent.
+ * - `reread`: tokens later calls read again, booked at session end as one row per session, hook surface and UTC day of the calls.
  */
-export type TokenEvent = 'inject' | 'skip' | 'reset';
+export type TokenEvent = 'inject' | 'skip' | 'reset' | 'reread';
 /** Rows older than this are pruned on write. */
 export declare const TOKEN_LEDGER_RETENTION_DAYS = 90;
 /**
@@ -33,7 +37,7 @@ export interface TokenUse {
     sessionId?: string | null;
     surface: TokenSurface;
     event: TokenEvent;
-    /** Memories (and continuity blocks) in the text. */
+    /** Memories (and continuity blocks) in the text; for a `reread`, how many times blocks were read again. */
     items: number;
     /** Estimated tokens of the text; for a `skip`, the tokens not sent. */
     tokens: number;
@@ -77,6 +81,8 @@ export interface TokenSurfaceSummary {
     skipped: number;
     /** Tokens those skipped blocks would have cost. */
     tokensAvoided: number;
+    /** Tokens of these blocks that later model calls read again, from sessions that have ended; 0 off {@link REREAD_SURFACES}. */
+    tokensReread: number;
     /** Distinct session ids seen (rows without one are not counted). */
     sessions: number;
 }
@@ -87,20 +93,32 @@ export interface TokenSummary {
     surfaces: TokenSurfaceSummary[];
     totalTokens: number;
     totalTokensAvoided: number;
+    totalTokensReread: number;
     /** Mean tokens sent per session, over rows that carry a session id. */
     meanTokensPerSession: number;
+    /** Distinct session ids in the window. */
+    sessions: number;
+    /** Sessions that sent, skipped or re-read a {@link REREAD_SURFACES} block, the ones whose re-reads can be counted. */
+    hookSessions: number;
+    /** Sessions whose re-reads were counted at session end; open or crashed sessions are not. */
+    rereadSessions: number;
 }
 /**
  * Sum the ledger for one tenant since `sinceIso`. Surfaces with no rows are
  * omitted.
  */
 export declare function summarizeTokenUse(db: DatabaseSyncLike, tenantId: string, sinceIso: string): TokenSummary;
-/**
- * The `session_id` of a Claude Code hook payload on stdin, or null when the
- * text is empty, malformed, has no non-empty session id, or (with
- * `requiredSource`) a different `source`.
- */
+/** JSON-value string check without a runtime `typeof` (anti-slop rule). */
+interface ModelTagged {
+    model?: unknown;
+}
+/** Claude Code writes its own API errors and limit notices as assistant lines from this model; no model call made them. */
+export declare function isSyntheticMessage(message: ModelTagged): boolean;
+/** A hook payload's non-empty `session_id`, or null; with `requiredSource`, also null when its `source` differs. */
 export declare function hookPayloadSessionId(stdinText: string | undefined, requiredSource?: string | null): string | null;
+/** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
+ *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
+export declare function isSubagentPayload(stdinText: string | undefined): boolean;
 /** Tokens hippo sent and skipped in one session, for {@link tokensBySession}. */
 export interface SessionTokens {
     sessionId: string;
@@ -117,4 +135,24 @@ export interface SessionTokens {
  * transcript file name, so these join to the host's own usage records.
  */
 export declare function tokensBySession(db: DatabaseSyncLike, tenantId: string, sinceIso: string): SessionTokens[];
+/** One model API call in a host transcript, for {@link recordRereads}. */
+export interface ApiCall {
+    /** Epoch milliseconds of the call's first transcript line. */
+    at: number;
+    /** Compactions before the call, in file order. */
+    compactions: number;
+}
+/** What {@link readApiCalls} found in a transcript. */
+export interface TranscriptCalls {
+    calls: ApiCall[];
+    /** Candidate lines that were not valid JSON, skipped. */
+    malformed: number;
+}
+/** Main-thread model calls in a Claude Code transcript, in file order; rejects when the file cannot be read. */
+export declare function readApiCalls(transcriptPath: string): Promise<TranscriptCalls>;
+/** Calls that carried a block sent at `at` (epoch ms): every later call in the first later call's context window. */
+export declare function carryingCalls(calls: readonly ApiCall[], at: number): ApiCall[];
+/** Replace a session's `reread` rows in one transaction, one per {@link REREAD_SURFACES} surface and UTC day; returns the tokens booked. */
+export declare function recordRereads(db: DatabaseSyncLike, tenantId: string, sessionId: string, calls: readonly ApiCall[]): number;
+export {};
 //# sourceMappingURL=token-ledger.d.ts.map

package/dist/token-ledger.js

@@ -3,9 +3,13 @@
  * and how many tokens it costs.
  *
  * One row per block of memory text sent to an agent, on every surface: the
- * per-prompt hook, `hippo context`, `hippo recall`, the MCP tools and the
- * HTTP API. The ledger answers the question a buyer asks first ("what does
- * this cost me per session?") and is the input for the token-savings evals.
+ * per-prompt hook, the block `hippo compact-resume` restores after compaction,
+ * `hippo context`, `hippo recall`, the MCP tools and the HTTP API. The ledger
+ * answers the question a buyer asks first ("what does this cost me per
+ * session?") and is the input for the token-savings evals.
+ *
+ * Every later model call re-reads a sent block until the host compacts; at session end the worker counts
+ * those calls from the transcript as `reread` rows for the {@link REREAD_SURFACES} blocks, dated by call day.
  *
  * It also backs TE2, inject only on change: the per-prompt hook compares the
  * hash of the block it is about to send with the last block it sent in the
@@ -15,15 +19,19 @@
  * every budget in hippo uses. Rows hold counts, surfaces, session ids and
  * hashes, never memory content or query text.
  *
- * DB-only helpers: the caller owns the handle. Writes are best-effort at the
- * call sites; a ledger failure must never break recall.
+ * DB helpers take the caller's handle; {@link readApiCalls} streams one
+ * transcript file. Writes are best-effort at the call sites; a ledger failure
+ * must never break recall.
  */
 import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
 /** All surfaces, in report order. */
 export const TOKEN_SURFACES = [
-    'hook', 'hook_recall', 'context', 'recall', 'mcp_recall', 'mcp_context',
+    'hook', 'hook_recall', 'compact_resume', 'context', 'recall', 'mcp_recall', 'mcp_context',
     'http_recall', 'http_context', 'http_assemble',
 ];
+/** Surfaces whose re-reads are counted: only a hook payload tells a sub-agent's block from its parent's, as both carry one session id. */
+export const REREAD_SURFACES = ['hook', 'hook_recall', 'compact_resume'];
 /** Rows older than this are pruned on write. */
 export const TOKEN_LEDGER_RETENTION_DAYS = 90;
 /**
@@ -90,6 +98,7 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
             SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens,
             SUM(CASE WHEN event = 'skip' THEN 1 ELSE 0 END) AS skipped,
             SUM(CASE WHEN event = 'skip' THEN tokens ELSE 0 END) AS avoided,
+            SUM(CASE WHEN event = 'reread' THEN tokens ELSE 0 END) AS reread,
             COUNT(DISTINCT session_id) AS sessions
      FROM token_ledger
      WHERE tenant_id = ? AND ts >= ?
@@ -106,14 +115,17 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
             tokens: Number(r.tokens),
             skipped: Number(r.skipped),
             tokensAvoided: Number(r.avoided),
+            tokensReread: Number(r.reread),
             sessions: Number(r.sessions),
         });
     }
-    // SAFETY: the SELECT names exactly these two aggregate columns.
+    // SAFETY: the SELECT names exactly these four aggregate columns.
     const perSession = db.prepare(`SELECT COUNT(DISTINCT session_id) AS sessions,
+            COUNT(DISTINCT CASE WHEN event <> 'reset' AND surface IN (${REREAD_SURFACES.map(() => '?').join(', ')}) THEN session_id END) AS hook_sessions,
+            COUNT(DISTINCT CASE WHEN event = 'reread' THEN session_id END) AS reread_sessions,
             SUM(CASE WHEN event = 'inject' THEN tokens ELSE 0 END) AS tokens
      FROM token_ledger
-     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL`).get(tenantId, sinceIso);
+     WHERE tenant_id = ? AND ts >= ? AND session_id IS NOT NULL`).get(...REREAD_SURFACES, tenantId, sinceIso);
     const sessionCount = Number(perSession?.sessions ?? 0);
     const sessionTokens = Number(perSession?.tokens ?? 0);
     return {
@@ -121,10 +133,17 @@ export function summarizeTokenUse(db, tenantId, sinceIso) {
         surfaces,
         totalTokens: surfaces.reduce((s, x) => s + x.tokens, 0),
         totalTokensAvoided: surfaces.reduce((s, x) => s + x.tokensAvoided, 0),
+        totalTokensReread: surfaces.reduce((s, x) => s + x.tokensReread, 0),
         meanTokensPerSession: sessionCount > 0 ? Math.round(sessionTokens / sessionCount) : 0,
+        sessions: sessionCount,
+        hookSessions: Number(perSession?.hook_sessions ?? 0),
+        rereadSessions: Number(perSession?.reread_sessions ?? 0),
     };
 }
-/** JSON-value string check without a runtime `typeof` (anti-slop rule). */
+/** Claude Code writes its own API errors and limit notices as assistant lines from this model; no model call made them. */
+export function isSyntheticMessage(message) {
+    return message.model === '<synthetic>';
+}
 function isJsonString(value) {
     return value !== undefined && value !== null && value.constructor === String;
 }
@@ -132,31 +151,35 @@ function isJsonString(value) {
 function isJsonObject(value) {
     return value !== undefined && value !== null && !Array.isArray(value) && value.constructor === Object;
 }
-/**
- * The `session_id` of a Claude Code hook payload on stdin, or null when the
- * text is empty, malformed, has no non-empty session id, or (with
- * `requiredSource`) a different `source`.
- */
-export function hookPayloadSessionId(stdinText, requiredSource = null) {
+/** A Claude Code hook payload on stdin as a JSON object; null when empty, malformed or not an object. */
+function parseHookPayload(stdinText) {
     if (!stdinText || stdinText.trim() === '')
         return null;
-    let payload;
     try {
         // SAFETY: JSON.parse returns a JSON value by definition.
-        payload = JSON.parse(stdinText.trim());
+        const payload = JSON.parse(stdinText.trim());
+        return isJsonObject(payload) ? payload : null;
     }
     catch {
         return null;
     }
-    if (!isJsonObject(payload))
-        return null;
-    const sessionId = payload.session_id;
-    if (!isJsonString(sessionId) || sessionId.trim() === '')
+}
+/** A hook payload's non-empty `session_id`, or null; with `requiredSource`, also null when its `source` differs. */
+export function hookPayloadSessionId(stdinText, requiredSource = null) {
+    const payload = parseHookPayload(stdinText);
+    const sessionId = payload?.session_id;
+    if (!payload || !isJsonString(sessionId) || sessionId.trim() === '')
         return null;
     if (requiredSource !== null && payload.source !== requiredSource)
         return null;
     return sessionId;
 }
+/** Whether a hook fired inside a sub-agent, the only payload with `agent_id` (https://code.claude.com/docs/en/hooks#common-input-fields).
+ *  Its `session_id` is the parent's, so a sub-agent's blocks and compactions must not count as the parent's. */
+export function isSubagentPayload(stdinText) {
+    const agentId = parseHookPayload(stdinText)?.agent_id;
+    return isJsonString(agentId) && agentId.trim() !== '';
+}
 /**
  * Ledger totals per session id since `sinceIso`, across every surface.
  * Claude Code hook rows carry the host's session id, which is also the
@@ -178,4 +201,100 @@ export function tokensBySession(db, tenantId, sinceIso) {
         injections: Number(r.injections),
     }));
 }
+/** Main-thread model calls in a Claude Code transcript, in file order; rejects when the file cannot be read. */
+export async function readApiCalls(transcriptPath) {
+    const file = await open(transcriptPath);
+    const calls = [];
+    const seen = new Set();
+    let compactions = 0;
+    let malformed = 0;
+    try {
+        for await (const line of file.readLines({ encoding: 'utf8' })) {
+            // Transcripts can pass 100 MB, so only lines that can be a call or a boundary are parsed.
+            if (!line.includes('"usage"') && !line.includes('"compact_boundary"'))
+                continue;
+            let entry;
+            try {
+                // SAFETY: JSON.parse returns a JSON value by definition.
+                entry = JSON.parse(line);
+            }
+            catch {
+                malformed += 1; // reported by the caller: one torn line must not void the session
+                continue;
+            }
+            // Sidechain calls, sidechain compactions and `<synthetic>` messages never touch the main context.
+            if (!isJsonObject(entry) || entry.isSidechain === true)
+                continue;
+            if (entry.subtype === 'compact_boundary') {
+                compactions += 1;
+                continue;
+            }
+            // One call spans lines sharing a message id.
+            const message = entry.message;
+            if (entry.type !== 'assistant' || !isJsonObject(message))
+                continue;
+            if (!isJsonObject(message.usage) || isSyntheticMessage(message) || !isJsonString(message.id))
+                continue;
+            if (seen.has(message.id))
+                continue;
+            seen.add(message.id);
+            const at = isJsonString(entry.timestamp) ? Date.parse(entry.timestamp) : Number.NaN;
+            if (!Number.isNaN(at))
+                calls.push({ at, compactions });
+        }
+    }
+    finally {
+        await file.close();
+    }
+    return { calls, malformed };
+}
+/** Calls that carried a block sent at `at` (epoch ms): every later call in the first later call's context window. */
+export function carryingCalls(calls, at) {
+    // Windows come from file order, not boundary timestamps: the compact-resume block is booked before its boundary's timestamp.
+    const first = calls.find((call) => call.at > at);
+    if (!first)
+        return [];
+    return calls.filter((call) => call.at > at && call.compactions === first.compactions);
+}
+/** Replace a session's `reread` rows in one transaction, one per {@link REREAD_SURFACES} surface and UTC day; returns the tokens booked. */
+export function recordRereads(db, tenantId, sessionId, calls) {
+    db.exec('BEGIN IMMEDIATE');
+    let committed = false;
+    try {
+        // SAFETY: the SELECT names exactly these three columns.
+        const rows = db.prepare(`SELECT ts, surface, tokens FROM token_ledger
+       WHERE tenant_id = ? AND session_id = ? AND event = 'inject' AND surface IN (${REREAD_SURFACES.map(() => '?').join(', ')})`).all(tenantId, sessionId, ...REREAD_SURFACES);
+        const days = new Map();
+        const add = (surface, at, rereads, tokens) => {
+            const key = `${surface} ${new Date(at).toISOString().slice(0, 10)}`;
+            const day = days.get(key) ?? { surface, at, rereads: 0, tokens: 0 };
+            days.set(key, { surface, at: Math.max(day.at, at), rereads: day.rereads + rereads, tokens: day.tokens + tokens });
+        };
+        for (const row of rows) {
+            const sentAt = Date.parse(row.ts);
+            // Dated by when the calls happened, so a --days window counts re-reads in it; the empty send-day row keeps the session in coverage.
+            add(row.surface, sentAt, 0, 0);
+            // The first carrying call is the send itself; every later one is a re-read.
+            for (const call of carryingCalls(calls, sentAt).slice(1))
+                add(row.surface, call.at, 1, Number(row.tokens));
+        }
+        db.prepare(`DELETE FROM token_ledger WHERE tenant_id = ? AND session_id = ? AND event = 'reread'`).run(tenantId, sessionId);
+        for (const day of days.values()) {
+            recordTokenUse(db, {
+                tenantId, sessionId, surface: day.surface, event: 'reread', items: day.rereads, tokens: day.tokens, now: new Date(day.at).toISOString(),
+            });
+        }
+        db.exec('COMMIT');
+        committed = true;
+        return [...days.values()].reduce((sum, day) => sum + day.tokens, 0);
+    }
+    finally {
+        if (!committed) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* preserve the original throw */ }
+        }
+    }
+}
 //# sourceMappingURL=token-ledger.js.map

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.52.8";
+export declare const PACKAGE_VERSION = "1.53.0";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.52.8';
+export const PACKAGE_VERSION = '1.53.0';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {