hippo-memory 1.52.7 → 1.52.9

package/dist/shared.js

@@ -9,13 +9,14 @@ import * as path from 'path';
 import { generateId } from './memory.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 +71,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 +106,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 +134,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 +175,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 +195,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 +204,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 +220,19 @@ 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',
+]);
+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',
+]);
 /**
  * Estimate how well a memory would transfer to other projects.
  * Returns 0..1 where >0.5 = good candidate for sharing.
@@ -301,10 +302,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 +358,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 +392,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))) {
+            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
@@ -457,7 +462,7 @@ export function autoShare(localRoot, options = {}) {
 }
 /**
  * Copy all global memories into the local store.
- * Skips entries that already exist locally (by ID or by near-identical content).
+ * Skips entries that already exist locally, by ID or by text (promote and share copy under a new ID).
  * Returns the count of newly copied entries.
  */
 export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
@@ -468,6 +473,8 @@ export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
     // the local-root context provides one.
     const globalEntries = loadAllEntries(globalRoot);
     const localIndex = loadIndex(localRoot);
+    const textKey = (e) => `${e.tenantId}\n${e.content}`;
+    const localText = new Set(loadAllEntries(localRoot).map(textKey));
     // v39 (codex P1-4): syncing down must not re-import what ambient context
     // excludes - other-project rows are skipped by default and secret rows
     // are never copied. origin_project is preserved on the copy (writeEntry
@@ -484,6 +491,8 @@ export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
         // Skip if already present by ID
         if (localIndex.entries[entry.id])
             continue;
+        if (localText.has(textKey(entry)))
+            continue;
         if (detectSecret(entry).flagged)
             continue;
         if (!opts.includeCrossProject &&
@@ -499,6 +508,7 @@ export function syncGlobalToLocal(localRoot, globalRoot, opts = {}) {
             }
             throw err;
         }
+        localText.add(textKey(entry));
         count++;
     }
     if (rejected > 0) {

package/dist/store.d.ts

@@ -645,6 +645,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.
@@ -652,12 +653,10 @@ export declare function loadLatestHandoff(hippoRoot: string, tenantId: string, s
 export declare function loadHandoffById(hippoRoot: string, tenantId: string, id: number): SessionHandoff | null;
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export declare function stampHandoffOutcome(hippoRoot: string, tenantId: string, sessionId: string, outcome: HandoffOutcome): number;
-/**
- * Auto-write a handoff at session-end from the session's active snapshot (DF1 T3).
+/** Auto-write a handoff at session-end (DF1 T3) from the session's active snapshot, else from `derived`, its transcript state.
  * @param evidence best-effort git state; outcome comes from the newest session_complete event.
- * @returns null unless the snapshot belongs to sessionId and no newer handoff already covers it.
- */
-export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null): SessionHandoff | null;
+ * @returns null when neither source is the session's, a newer handoff covers the snapshot, or the session's latest handoff was not read off its transcript. */
+export declare function writeSessionEndHandoff(hippoRoot: string, tenantId: string, sessionId: string, evidence: HandoffEvidence | null, derived?: Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null): SessionHandoff | null;
 export declare function transitionCard(db: DatabaseSyncLike, tenantId: string, cardId: string, from: CardStatus[], to: CardStatus, extra?: {
     setSql?: string;
     whereSql?: string;

package/dist/store.js

@@ -16,6 +16,7 @@ import { isRecallBoostAblated } from './ablation.js';
 import { rarestPromptTerms, RAREST_TERM_COUNT } from './prompt-recall.js';
 import { appendAuditEvent } from './audit.js';
 import { resolveTenantId } from './tenant.js';
+import { redactSecretsStrict } from './secret-detect.js';
 import { deriveOriginProject, originFromSource, findHippoStoreDir, realpathOrResolve } from './project-identity.js';
 import { checkRejectionGuard, RejectedValueError, rejectionDigest, normalizeValueForRejection, insertRejectedValue, findRejectedValue, } from './rejection.js';
 // AT1 (plan §5): resolveConflict's kind-aware loser removal needs
@@ -2146,7 +2147,7 @@ export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot) {
         const result = db.prepare(`
       INSERT INTO task_snapshots(task, summary, next_step, status, source, session_id, scope, tenant_id, created_at, updated_at)
       VALUES (?, ?, ?, 'active', ?, ?, ?, ?, ?, ?)
-    `).run(snapshot.task, snapshot.summary, snapshot.next_step, snapshot.source ?? 'cli', snapshot.session_id ?? null, snapshot.scope ?? null, tenantId, now, now);
+    `).run(redactSecretsStrict(snapshot.task), redactSecretsStrict(snapshot.summary), redactSecretsStrict(snapshot.next_step), snapshot.source ?? 'cli', snapshot.session_id ?? null, snapshot.scope ?? null, tenantId, now, now);
         db.exec('COMMIT');
         const id = Number(result.lastInsertRowid ?? 0);
         // SAFETY: row's shape matches the ten columns named in the SELECT above.
@@ -2834,6 +2835,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.
@@ -2904,20 +2909,28 @@ export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
         closeHippoDb(db);
     }
 }
-/**
- * Auto-write a handoff at session-end from the session's active snapshot (DF1 T3).
+/** Auto-write a handoff at session-end (DF1 T3) from the session's active snapshot, else from `derived`, its transcript state.
  * @param evidence best-effort git state; outcome comes from the newest session_complete event.
- * @returns null unless the snapshot belongs to sessionId and no newer handoff already covers it.
- */
-export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence) {
+ * @returns null when neither source is the session's, a newer handoff covers the snapshot, or the session's latest handoff was not read off its transcript. */
+export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence, derived = null) {
     assertTenantId('writeSessionEndHandoff', tenantId);
-    const snapshot = loadActiveTaskSnapshot(hippoRoot, tenantId);
-    if (!snapshot || snapshot.session_id !== sessionId)
-        return null;
+    const active = loadActiveTaskSnapshot(hippoRoot, tenantId);
     const existing = loadLatestHandoff(hippoRoot, tenantId, sessionId);
-    // Strict '>': a same-millisecond tie must not swallow the session's only write (test 6e).
-    if (existing && existing.updatedAt > snapshot.updated_at)
-        return null;
+    let snapshot;
+    let handoffEvidence = evidence;
+    if (active && active.session_id === sessionId) {
+        // Strict '>': a same-millisecond tie must not swallow the session's only write (test 6e).
+        if (existing && existing.updatedAt > active.updated_at)
+            return null;
+        snapshot = active;
+    }
+    else {
+        // Only an earlier transcript read gives way; `hippo handoff create` and unmarked older handoffs keep winning.
+        if (!derived || (existing && existing.evidence?.derivedFrom !== 'transcript'))
+            return null;
+        snapshot = { ...derived, scope: null };
+        handoffEvidence = { ...evidence, derivedFrom: 'transcript' };
+    }
     const db = openHippoDb(hippoRoot);
     let outcome = null;
     try {
@@ -2947,7 +2960,7 @@ export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence)
         nextAction: snapshot.next_step,
         artifacts: carryForward ? existing.artifacts : [],
         scope: snapshot.scope,
-        evidence,
+        evidence: handoffEvidence,
         outcome,
         constraints: carryForward ? existing.constraints : undefined,
         targetRuntime: carryForward ? existing.targetRuntime : undefined,

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.7";
+export declare const PACKAGE_VERSION = "1.52.9";
 /** 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