@herbertgao/pi-extensions 2026.8.7 → 2026.8.8

package/node_modules/pi-lens/dist/clients/cache-observability.js

@@ -14,7 +14,14 @@
  *      transformation, placement, injection sources, and privacy-preserving
  *      hashes. This is what pi-lens observed locally, not the final provider
  *      request after other context handlers have run and not a provider cache
- *      result.
+ *      result. #1938: this record used to also carry a `prefixObservation` /
+ *      `firstMessageChange` pair derived from a SEPARATE bounded hash of the
+ *      pre-injection prefix (capped at `MAX_HASHED_MESSAGES` messages /
+ *      `MAX_HASHED_CONTENT_CHARS` chars). Every real session's transcript
+ *      exceeds that cap almost immediately, so the pair reported "unknown" on
+ *      97% of records — dead weight in every record, answering nothing. The
+ *      pair is removed; signal 3 below (`cache_prefix_break`) already covers
+ *      first-message stability with an unbounded hash and never truncates.
  *
  *   3. Request-side prefix stability (`cache_prefix_break`) — a content hash of
  *      `messages[0]` observed on every `context` call. After #1016 the first
@@ -22,12 +29,20 @@
  *      flags that something (pi-lens or otherwise) broke the cache prefix. This
  *      remains a local observation, never a provider cache-miss claim.
  *
+ * #1071 adds miss ATTRIBUTION on top of those three, without a new phase. Each
+ * `cache_usage` record carries the inter-turn gap and a `cacheMissCause`
+ * verdict, and each `cache_context` record splits a mixed injection payload by
+ * contributing source. Both ride records that already fire once per turn, and
+ * both derive from state this module already keeps in process — nothing reads
+ * latency.log back.
+ *
  * All paths are defensive: `usage` (and its fields) may be absent on older
  * hosts or non-assistant messages, so every access is guarded and the handlers
  * never throw — on error they `dbg(...)` and no-op, like the other index.ts
  * event handlers.
  */
 import { createHash } from "node:crypto";
+import { lazyEnvNumber } from "./env-utils.js";
 import { logLatency } from "./latency-logger.js";
 /** RuntimeCoordinator's counter is process-global when sessions share a host. */
 const PROCESS_TURN_SCOPE = "process-global-runtime";
@@ -43,6 +58,214 @@ const MAX_REPORTED_MESSAGES = 10_000;
 const MAX_INJECTED_CHARS = 16_384;
 const MAX_INJECTED_BYTES = 65_536;
 let contextObservationCounter = 0;
+/**
+ * Documented deterministic char→token estimate. Four characters per token is
+ * the same ratio #1071's issue body used to size the sampled injections. It is
+ * an ESTIMATE: never present a value derived from it as provider-measured
+ * usage.
+ */
+const CHARS_PER_ESTIMATED_TOKEN = 4;
+/**
+ * Idle gap after which a provider prompt cache entry is assumed expired.
+ *
+ * The gap this is compared against is measured to REQUEST time, not to the
+ * `message_end` that follows it — see {@link resolveInterTurnGap}. The provider
+ * looks the cache up when the request arrives, so the response's own generation
+ * time is not idle time and must not count toward expiry.
+ *
+ * Evidence (2026-08-21 KV-cache investigation, 63 sessions, 2,288 turns): the
+ * 34 zero-`cacheRead` turns had a MEDIAN inter-turn gap of 166s, against 9s for
+ * every other turn. Those 34 turns carried 6.96M fresh input tokens, 35.1% of
+ * all fresh input in the window. 60s sits between the two populations and
+ * matches the documented 5-minute-minus-safety-margin behavior of the shortest
+ * provider TTL tier we run against. Override with
+ * `PI_LENS_PROVIDER_CACHE_TTL_MS` when a provider's TTL differs.
+ */
+export const DEFAULT_PROVIDER_CACHE_TTL_MS = 60_000;
+const _providerCacheTtl = lazyEnvNumber("PI_LENS_PROVIDER_CACHE_TTL_MS", DEFAULT_PROVIDER_CACHE_TTL_MS);
+export const getProviderCacheTtlMs = _providerCacheTtl.get;
+export const _resetProviderCacheTtlForTests = _providerCacheTtl._resetForTests;
+/**
+ * A turn counts as "anomalously low" when it reads back less than half of what
+ * the previous turn read. The investigation's partial-break population (90
+ * turns, upper-bounded at 2.7M tokens) was selected by exactly this shape: a
+ * non-zero `cacheRead` well below the prior turn's, which a zero-read filter
+ * misses entirely.
+ */
+const LOW_CACHE_READ_RATIO = 0.5;
+/**
+ * Fresh input must exceed the estimated new content by this factor before a
+ * shortfall reads as provider-side eviction rather than as our own payload.
+ * The investigation upper-bounds a whole session's injections at ~2.7 tokens
+ * per turn, so fresh input several times the measured new content cannot be
+ * explained by what pi-lens added.
+ */
+const PARTIAL_EVICTION_INPUT_FACTOR = 4;
+/**
+ * Floor for the same rule, so a turn with almost no new content does not read
+ * as eviction on a handful of tokens.
+ */
+const PARTIAL_EVICTION_MIN_FRESH_TOKENS = 512;
+/**
+ * Cap on the per-session character accumulators used for attribution, and on a
+ * single transcript-growth measurement feeding them.
+ *
+ * This is deliberately NOT `MAX_INJECTED_CHARS`. That 16 KiB cap exists to keep
+ * the reported injection size small, and pi-lens injections average about 2.7
+ * estimated tokens per turn, so it is never reached in practice. Transcript
+ * growth is a different population: one ordinary tool result can add 20,000
+ * characters in a single turn. Measuring growth through the injection cap
+ * latched `attributionCharsCapped` on a routine turn and suppressed the
+ * `partial-eviction` verdict, which made the verdict near-unreachable (#1071
+ * review round 1, F2).
+ */
+const MAX_ATTRIBUTION_CHARS = 262_144;
+/** Byte companion to {@link MAX_ATTRIBUTION_CHARS}, at four bytes per char. */
+const MAX_ATTRIBUTION_BYTES = 1_048_576;
+const attributionBySession = new Map();
+function newAttributionState() {
+    return {
+        prefixBrokeSinceLastUsage: false,
+        injectedCharsSinceLastUsage: 0,
+        newTranscriptCharsSinceLastUsage: 0,
+        attributionCharsCapped: false,
+    };
+}
+/**
+ * Fetch (creating if absent) one session's attribution state, refreshing LRU
+ * recency and evicting the oldest entries past the cap — same bounding as
+ * {@link recordSessionHash}, so a long-lived process cycling through sessions
+ * cannot grow this map without limit.
+ */
+function attributionFor(key) {
+    const existing = attributionBySession.get(key);
+    const state = existing ?? newAttributionState();
+    attributionBySession.delete(key);
+    attributionBySession.set(key, state);
+    while (attributionBySession.size > MAX_TRACKED_SESSIONS) {
+        const oldest = attributionBySession.keys().next().value;
+        if (oldest === undefined)
+            break;
+        attributionBySession.delete(oldest);
+    }
+    return state;
+}
+/**
+ * Fold one `context` observation into the session's attribution state: how much
+ * pi-lens injected, and how much the transcript itself grew since the previous
+ * observation. The transcript delta is what the "far above the injected and new
+ * content" rule measures fresh input against. The first observation in a
+ * session only anchors the message-count baseline, because there is no earlier
+ * point to measure growth from.
+ */
+function recordContextAttribution(key, existingMessages, injectedSize) {
+    const state = attributionFor(key);
+    const baseline = Math.min(state.lastObservedMessageCount ?? existingMessages.length, existingMessages.length);
+    const grown = measureTranscriptGrowth(existingMessages.slice(baseline));
+    state.injectedCharsSinceLastUsage = Math.min(MAX_ATTRIBUTION_CHARS, state.injectedCharsSinceLastUsage + injectedSize.chars);
+    state.newTranscriptCharsSinceLastUsage = Math.min(MAX_ATTRIBUTION_CHARS, state.newTranscriptCharsSinceLastUsage + grown.chars);
+    if (injectedSize.capped ||
+        grown.capped ||
+        state.injectedCharsSinceLastUsage >= MAX_ATTRIBUTION_CHARS ||
+        state.newTranscriptCharsSinceLastUsage >= MAX_ATTRIBUTION_CHARS) {
+        // The accumulators are now floors, not totals. The verdict rules must not
+        // treat a floor as a measured value.
+        state.attributionCharsCapped = true;
+    }
+    state.lastObservedMessageCount = existingMessages.length;
+    // #1071 review round 1, F1: this handler runs at REQUEST time, which is when
+    // the provider looks the prompt cache up. Stamping it here is what lets the
+    // gap exclude the response's own generation time.
+    state.lastContextAtMs = Date.now();
+}
+/**
+ * Idle milliseconds before this turn's provider request.
+ *
+ * Measuring `message_end` to `message_end` would fold the response's own
+ * generation time into the gap, and generation dominates: over a real corpus
+ * the median generation time is 7,407 ms against a median true idle of 228 ms,
+ * a factor of 30. At the 60s threshold, 8.7% of consecutive pairs measure over
+ * on the message-end basis while only 3.3% were truly idle over. That is a 3.4x
+ * inflation of `ttl-expired`, which would have confirmed the investigation's
+ * hypothesis by construction (#1071 review round 1, F1).
+ */
+function resolveInterTurnGap(state, nowMs) {
+    if (state.lastUsageAtMs === undefined) {
+        return { gapMs: null, basis: "no-prior-turn" };
+    }
+    if (state.lastContextAtMs !== undefined) {
+        return {
+            gapMs: Math.max(0, state.lastContextAtMs - state.lastUsageAtMs),
+            basis: "request-time",
+        };
+    }
+    return {
+        gapMs: Math.max(0, nowMs - state.lastUsageAtMs),
+        basis: "message-end-fallback",
+    };
+}
+function estimateTokens(chars) {
+    return Math.ceil(chars / CHARS_PER_ESTIMATED_TOKEN);
+}
+/**
+ * Classify a turn's prompt-cache shortfall. Returns `null` when there is
+ * nothing to explain: no prior usage record in this session (the first turn
+ * legitimately reads nothing), an unreadable `cacheRead`, or a healthy read.
+ *
+ * Rules, in the order they are applied, each stated with the evidence behind
+ * it (2026-08-21 investigation, 63 sessions, 2,288 turns, 94.2% overall hit
+ * rate):
+ *
+ *   1. `prefix-broke` — a `cache_prefix_break` CHANGE fired in this session
+ *      since the previous usage record. This is a DIRECT local observation of
+ *      the cause, so it outranks the timing heuristics below. The window was
+ *      byte-stable throughout, so this verdict should stay rare; if it does
+ *      not, #1016's fix has regressed.
+ *   2. `ttl-expired` — the gap since the previous usage record reached the
+ *      provider TTL threshold. The 34 zero-read turns had a median gap of 166s
+ *      against 9s elsewhere, and carried 35.1% of all fresh input.
+ *   3. `partial-eviction` — a non-zero but low read, where fresh input runs far
+ *      above the new content we measured. pi-lens injections average ~2.7
+ *      estimated tokens per turn, so they cannot account for a multiple of the
+ *      measured content; the remainder is provider-side eviction, typically at
+ *      a context limit. Suppressed when the character accumulators were capped,
+ *      because a floor estimate would manufacture the verdict.
+ *   4. `unknown` — a real shortfall with no local explanation. Reported, never
+ *      guessed at.
+ */
+function classifyCacheMiss(args) {
+    const { cacheRead, priorCacheRead } = args;
+    if (typeof cacheRead !== "number" || !Number.isFinite(cacheRead))
+        return null;
+    // No baseline turn in this session: a first turn reads zero because nothing
+    // is cached yet, not because anything went wrong.
+    if (typeof priorCacheRead !== "number" || !Number.isFinite(priorCacheRead)) {
+        return null;
+    }
+    let kind;
+    if (cacheRead === 0) {
+        kind = "zero-read";
+    }
+    else if (priorCacheRead > 0 &&
+        cacheRead < priorCacheRead * LOW_CACHE_READ_RATIO) {
+        kind = "low-read";
+    }
+    else {
+        return null;
+    }
+    if (args.prefixBroke)
+        return { kind, cause: "prefix-broke" };
+    if (args.interTurnGapMs !== null && args.interTurnGapMs >= args.ttlMs) {
+        return { kind, cause: "ttl-expired" };
+    }
+    if (kind === "low-read" &&
+        !args.attributionCharsCapped &&
+        args.input >
+            Math.max(PARTIAL_EVICTION_MIN_FRESH_TOKENS, args.estimatedNewTokens * PARTIAL_EVICTION_INPUT_FACTOR)) {
+        return { kind, cause: "partial-eviction" };
+    }
+    return { kind, cause: "unknown" };
+}
 function boundedHashScalar(value, state) {
     if (value === null)
         return "null";
@@ -123,65 +346,63 @@ function hashMessageSequence(messages) {
         contentTruncated: state.contentTruncated,
     };
 }
-function messageTextSize(content) {
+/** Bounds for reporting an injected payload's size in the record. */
+const INJECTED_LIMITS = {
+    maxChars: MAX_INJECTED_CHARS,
+    maxBytes: MAX_INJECTED_BYTES,
+};
+/** Bounds for the transcript-growth accumulator that feeds the verdict. */
+const TRANSCRIPT_LIMITS = {
+    maxChars: MAX_ATTRIBUTION_CHARS,
+    maxBytes: MAX_ATTRIBUTION_BYTES,
+};
+function messageTextSize(content, limits) {
     if (typeof content === "string") {
-        const chars = Math.min(content.length, MAX_INJECTED_CHARS);
+        const chars = Math.min(content.length, limits.maxChars);
         return {
             chars,
-            bytes: Math.min(Buffer.byteLength(content.slice(0, chars), "utf8"), MAX_INJECTED_BYTES),
+            bytes: Math.min(Buffer.byteLength(content.slice(0, chars), "utf8"), limits.maxBytes),
         };
     }
     const bounded = boundedHashValue(content);
     return {
-        chars: Math.min(bounded.length, MAX_INJECTED_CHARS),
-        bytes: Math.min(Buffer.byteLength(bounded.slice(0, MAX_INJECTED_CHARS), "utf8"), MAX_INJECTED_BYTES),
+        chars: Math.min(bounded.length, limits.maxChars),
+        bytes: Math.min(Buffer.byteLength(bounded.slice(0, limits.maxChars), "utf8"), limits.maxBytes),
     };
 }
-function measureInjectedMessages(messages) {
+function measureMessages(messages, limits) {
     let chars = 0;
     let bytes = 0;
     const measuredCount = Math.min(messages.length, MAX_REPORTED_MESSAGES);
     for (let i = 0; i < measuredCount; i++) {
         const message = messages[i];
-        const size = messageTextSize(message?.content);
-        chars = Math.min(MAX_INJECTED_CHARS, chars + size.chars);
-        bytes = Math.min(MAX_INJECTED_BYTES, bytes + size.bytes);
-        if (chars === MAX_INJECTED_CHARS || bytes === MAX_INJECTED_BYTES)
+        const size = messageTextSize(message?.content, limits);
+        chars = Math.min(limits.maxChars, chars + size.chars);
+        bytes = Math.min(limits.maxBytes, bytes + size.bytes);
+        if (chars === limits.maxChars || bytes === limits.maxBytes)
             break;
     }
     return {
         chars,
         bytes,
-        capped: chars >= MAX_INJECTED_CHARS || bytes >= MAX_INJECTED_BYTES,
+        capped: chars >= limits.maxChars || bytes >= limits.maxBytes,
     };
 }
-function sessionKey(sessionId) {
-    return sessionId?.trim() ? sessionId.trim() : NO_SESSION_KEY;
-}
-function prefixLengthForPlacement(placement, messageCount) {
-    if (placement === "insert-before-final") {
-        return Math.max(0, messageCount - 1);
-    }
-    if (placement === "prepend")
-        return 0;
-    return messageCount;
-}
-function resolvePrefixObservation(truncated, observation) {
-    if (truncated)
-        return "unknown";
-    return observation ?? "empty";
+/** Size of an injected payload, bounded for reporting. */
+function measureInjectedMessages(messages) {
+    return measureMessages(messages, INJECTED_LIMITS);
 }
-function prefixBaselineForObservation(observation) {
-    if (observation === "baseline")
-        return true;
-    if (observation === "empty" || observation === "unknown")
-        return null;
-    return false;
+/**
+ * Size of the transcript's own growth, bounded far higher. A routine tool
+ * result is an order of magnitude past the injection cap, and measuring it
+ * through that cap made `partial-eviction` near-unreachable (#1071 review
+ * round 1, F2).
+ */
+function measureTranscriptGrowth(messages) {
+    return measureMessages(messages, TRANSCRIPT_LIMITS);
 }
-function firstMessageChangeFor(truncated, before, after) {
-    if (truncated)
-        return "unknown";
-    return before !== after ? "changed" : "unchanged";
+function sessionKey(sessionId) {
+    return sessionId?.trim() ? sessionId.trim() : NO_SESSION_KEY;
 }
 /**
  * Log one bounded request-side observation for every `context` call. This is
@@ -197,34 +418,32 @@ export function observeCacheContext(args) {
     try {
         const existingMessages = args.existingMessages ?? [];
         const resultMessages = args.resultMessages ?? existingMessages;
-        const injectedMessages = args.injectedMessages ?? [];
+        // Drop empty slices before deriving anything: a source that contributed
+        // no message is not a contributor, and listing it would overstate the
+        // payload's provenance.
+        const injectionSlices = (args.injectionSlices ?? []).filter((slice) => slice.messages.length > 0);
+        const injectedMessages = injectionSlices.flatMap((slice) => slice.messages);
         const placement = args.placement ?? "none";
         const beforeSequence = hashMessageSequence(existingMessages);
         const afterSequence = hashMessageSequence(resultMessages);
-        const beforePrefixLength = prefixLengthForPlacement(placement, existingMessages.length);
-        const afterPrefixLength = Math.min(beforePrefixLength, resultMessages.length);
-        const beforePrefix = hashMessageSequence(existingMessages.slice(0, beforePrefixLength));
-        const afterPrefix = hashMessageSequence(resultMessages.slice(0, afterPrefixLength));
-        const beforeFirstSequence = existingMessages.length
-            ? hashMessageSequence([existingMessages[0]])
-            : undefined;
-        const afterFirstSequence = resultMessages.length
-            ? hashMessageSequence([resultMessages[0]])
-            : undefined;
-        const beforeFirst = beforeFirstSequence?.hash ?? null;
-        const afterFirst = afterFirstSequence?.hash ?? null;
-        const firstMessageHashTruncated = beforeFirstSequence?.truncated === true ||
-            beforeFirstSequence?.contentTruncated === true ||
-            afterFirstSequence?.truncated === true ||
-            afterFirstSequence?.contentTruncated === true;
-        const prefixHashTruncated = beforePrefix.truncated ||
-            afterPrefix.truncated ||
-            beforePrefix.contentTruncated ||
-            afterPrefix.contentTruncated;
-        const prefixObservation = resolvePrefixObservation(prefixHashTruncated, args.prefixObservation);
         const sizes = measureInjectedMessages(injectedMessages);
+        // Per-source split of a mixed payload (#1071 AC 2). The old record named
+        // which sources fired but attributed cost by CALL, so a turn carrying
+        // turn-findings plus an agent nudge was one undivided number.
+        const sourceBreakdown = injectionSlices.map((slice) => {
+            const sliceSize = measureInjectedMessages(slice.messages);
+            return {
+                source: slice.source,
+                messageCount: Math.min(slice.messages.length, MAX_REPORTED_MESSAGES),
+                chars: sliceSize.chars,
+                bytes: sliceSize.bytes,
+                estimatedTokens: estimateTokens(sliceSize.chars),
+                countsCapped: sliceSize.capped,
+            };
+        });
         const messageCountCapped = existingMessages.length > MAX_REPORTED_MESSAGES ||
             resultMessages.length > MAX_REPORTED_MESSAGES;
+        recordContextAttribution(sessionKey(args.sessionId), existingMessages, sizes);
         logLatency({
             type: "phase",
             filePath: "<pi-lens>",
@@ -240,39 +459,28 @@ export function observeCacheContext(args) {
                     ? { turnScope: SECONDARY_TURN_SCOPE }
                     : { turnIndex: args.turnIndex, turnScope: PROCESS_TURN_SCOPE }),
                 injectionEnabled: args.injectionEnabled,
-                injectionSources: Array.from(args.injectionSources ?? []),
+                injectionSources: sourceBreakdown.map((entry) => entry.source),
+                injectionSourceBreakdown: sourceBreakdown,
+                injectionOccurred: injectedMessages.length > 0,
                 injectedMessageCount: Math.min(injectedMessages.length, MAX_REPORTED_MESSAGES),
                 injectedMessageCountCapped: injectedMessages.length > MAX_REPORTED_MESSAGES,
                 injectedChars: sizes.chars,
                 injectedBytes: sizes.bytes,
+                injectedEstimatedTokens: estimateTokens(sizes.chars),
+                injectedTokenBasis: "chars-per-token-4-estimate-not-provider-measured",
                 injectedCountsCapped: sizes.capped,
                 existingMessageCount: Math.min(existingMessages.length, MAX_REPORTED_MESSAGES),
                 resultMessageCount: Math.min(resultMessages.length, MAX_REPORTED_MESSAGES),
                 messageCountCapped,
                 placement,
-                prefixObservation,
-                prefixObservationUnknown: prefixObservation === "unknown",
-                prefixBaseline: prefixBaselineForObservation(prefixObservation),
-                firstMessageChanged: firstMessageHashTruncated
-                    ? null
-                    : beforeFirst !== afterFirst,
-                firstMessageChange: firstMessageChangeFor(firstMessageHashTruncated, beforeFirst, afterFirst),
-                firstMessageHashTruncated,
-                beforeFirstMessageHash: beforeFirst,
-                afterFirstMessageHash: afterFirst,
                 beforeSequenceHash: beforeSequence.hash,
                 afterSequenceHash: afterSequence.hash,
-                beforePrefixHash: beforePrefix.hash,
-                afterPrefixHash: afterPrefix.hash,
                 sequenceHashTruncated: beforeSequence.truncated ||
                     afterSequence.truncated ||
                     beforeSequence.contentTruncated ||
                     afterSequence.contentTruncated,
                 sequenceMessageCountTruncated: beforeSequence.truncated || afterSequence.truncated,
                 sequenceContentHashTruncated: beforeSequence.contentTruncated || afterSequence.contentTruncated,
-                prefixHashTruncated,
-                prefixMessageCountTruncated: beforePrefix.truncated || afterPrefix.truncated,
-                prefixContentHashTruncated: beforePrefix.contentTruncated || afterPrefix.contentTruncated,
             },
         });
     }
@@ -301,6 +509,49 @@ export function logCacheUsage(message, dbg, context) {
         if (!usage || typeof usage !== "object")
             return;
         const u = usage;
+        // #1071: attribute the shortfall in-process, from state this module already
+        // keeps, so nothing re-reads latency.log.
+        const attributionKey = sessionKey(context?.sessionId);
+        const state = attributionFor(attributionKey);
+        const nowMs = Date.now();
+        const gap = resolveInterTurnGap(state, nowMs);
+        const interTurnGapMs = gap.gapMs;
+        const ttlMs = getProviderCacheTtlMs();
+        const estimatedNewTokens = estimateTokens(state.injectedCharsSinceLastUsage +
+            state.newTranscriptCharsSinceLastUsage);
+        const verdict = classifyCacheMiss({
+            cacheRead: u.cacheRead,
+            input: typeof u.input === "number" ? u.input : 0,
+            priorCacheRead: state.lastCacheRead,
+            interTurnGapMs,
+            ttlMs,
+            prefixBroke: state.prefixBrokeSinceLastUsage,
+            estimatedNewTokens,
+            attributionCharsCapped: state.attributionCharsCapped,
+        });
+        const priorCacheRead = typeof state.lastCacheRead === "number" ? state.lastCacheRead : null;
+        const injectedCharsSinceLastTurn = state.injectedCharsSinceLastUsage;
+        const newTranscriptCharsSinceLastTurn = state.newTranscriptCharsSinceLastUsage;
+        const attributionCharsCapped = state.attributionCharsCapped;
+        // This record is the turn boundary: reset the per-turn accumulators and
+        // re-arm the prefix-break flag so the next verdict describes the NEXT gap.
+        state.lastUsageAtMs = nowMs;
+        // A record whose `cacheRead` is absent or non-finite carries no baseline.
+        // Clear the stored one rather than keeping it: the next turn's gap would be
+        // one turn long while its baseline was two turns old, and a verdict built
+        // on that mismatch is worse than no verdict (#1071 review round 1, F4).
+        state.lastCacheRead =
+            typeof u.cacheRead === "number" && Number.isFinite(u.cacheRead)
+                ? u.cacheRead
+                : undefined;
+        state.prefixBrokeSinceLastUsage = false;
+        state.injectedCharsSinceLastUsage = 0;
+        state.newTranscriptCharsSinceLastUsage = 0;
+        state.attributionCharsCapped = false;
+        // Clear the request stamp too: the next turn measures from ITS request, and
+        // a turn whose `context` call pi-lens never saw must fall back rather than
+        // reuse this one.
+        state.lastContextAtMs = undefined;
         logLatency({
             type: "phase",
             filePath: "<pi-lens>",
@@ -315,6 +566,20 @@ export function logCacheUsage(message, dbg, context) {
                 output: u.output,
                 // `Usage.cost` is a breakdown object; the total is the headline number.
                 cost: u.cost?.total,
+                // Idle milliseconds before this turn's request, or null for the first
+                // record in the session. This is the field the 2026-08-21
+                // investigation had to reconstruct by hand-joining timestamps.
+                interTurnGapMs,
+                gapBasis: gap.basis,
+                // null means "nothing to explain", not "cause unknown"; `unknown` is
+                // the explicit no-local-explanation verdict.
+                cacheMissCause: verdict?.cause ?? null,
+                cacheMissKind: verdict?.kind ?? null,
+                cacheTtlThresholdMs: ttlMs,
+                priorCacheRead,
+                injectedCharsSinceLastTurn,
+                newTranscriptCharsSinceLastTurn,
+                attributionCharsCapped,
                 ...(context
                     ? {
                         // MessageEndEvent has no request/context id in the host API. These
@@ -455,6 +720,9 @@ export function observeCachePrefix(messages, turnIndex, sessionId, sessionRole,
             return "baseline";
         }
         if (currentHash !== previousHash) {
+            // #1071: arm the direct-cause flag the next `cache_usage` verdict reads.
+            // A locally observed prefix change outranks the timing heuristics.
+            attributionFor(key).prefixBrokeSinceLastUsage = true;
             logLatency({
                 type: "phase",
                 filePath: "<pi-lens>",
@@ -491,8 +759,17 @@ export function observeCachePrefix(messages, turnIndex, sessionId, sessionRole,
 export function clearCachePrefixSession(sessionId) {
     const key = sessionKey(sessionId);
     prefixHashBySession.delete(key);
+    // The miss-attribution state has the same lifetime and the same reason to be
+    // reclaimed at session end; leaving it would let a reused session id inherit
+    // a stale gap baseline and a stale prefix-break flag.
+    attributionBySession.delete(key);
 }
-/** Clear all per-session prefix hashes. For tests / session boundaries. */
+/**
+ * Clear all per-session prefix hashes and miss-attribution state. For tests and
+ * session boundaries. Both maps are cleared together so a test can never start
+ * with a half-reset session.
+ */
 export function resetCachePrefixObservation() {
     prefixHashBySession.clear();
+    attributionBySession.clear();
 }

package/node_modules/pi-lens/dist/clients/degradation-ledger.js

@@ -2,6 +2,7 @@
 import { logExtension } from "./extension-log.js";
 import { LEDGER_FIELD_MAX, truncateForLedger } from "./ledger-bounds.js";
 import { logLatency } from "./latency-logger.js";
+import { getSinkWriteFailures, resetSinkWriteFailures } from "./ndjson-logger.js";
 // Re-exported so existing importers keep one name for the ledger's bound.
 export { LEDGER_FIELD_MAX, truncateForLedger };
 const ENTRIES_PER_KIND = 20;
@@ -143,12 +144,28 @@ function boundedKind(value) {
     return groups.size < MAX_DISTINCT_KINDS - 1 ? kind : OVERFLOW_KIND;
 }
 export function getDegradationSummary() {
-    return [...groups.entries()].map(([kind, group]) => ({
+    const summary = [...groups.entries()].map(([kind, group]) => ({
         kind,
         count: group.count,
         droppedCount: group.count - group.entries.length,
         latestReasons: group.entries.map((entry) => ({ ...entry })),
     }));
+    // Folded in at read time, not written into `groups` (#1970) — see the
+    // `log-sink-write-failure` doc comment on `DegradationKind` for why this
+    // kind never goes through `recordDegradation`.
+    const sinkFailures = getSinkWriteFailures();
+    if (sinkFailures.length > 0) {
+        summary.push({
+            kind: "log-sink-write-failure",
+            count: sinkFailures.reduce((total, sink) => total + sink.droppedCount, 0),
+            droppedCount: 0,
+            latestReasons: sinkFailures.map((sink) => ({
+                subject: truncateForLedger(sink.file),
+                reason: truncateForLedger(`${sink.droppedCount} dropped write(s) after reopen-retry failed`),
+            })),
+        });
+    }
+    return summary;
 }
 function isRenderableSummary(value) {
     if (!Array.isArray(value))
@@ -197,6 +214,10 @@ export function resetDegradationLedger() {
     onceKeys.clear();
     tallies.clear();
     ledgerGeneration++;
+    // #1970, catalog shape 17: the sink write-failure tally is a
+    // process-lifetime latch too — it re-arms alongside the rest of the
+    // ledger rather than surviving past the session that observed it.
+    resetSinkWriteFailures();
 }
 export const DEGRADATION_ENTRIES_PER_KIND = ENTRIES_PER_KIND;
 export const DEGRADATION_MAX_DISTINCT_KINDS = MAX_DISTINCT_KINDS;