mixdog 1.3.5 → 1.4.1

package/src/runtime/agent/orchestrator/session/manager/turn-checkpoint-journal.mjs

@@ -39,6 +39,8 @@ import { join } from 'node:path';
 import { getPluginData } from '../../config.mjs';
 import { writeFileAtomicSync } from '../../../../shared/atomic-file.mjs';
 import { sanitizeContentForStoredHistory } from '../../providers/media-normalization.mjs';
+import { redactSettledText, sensitiveValuesVersion } from '../sensitive-values.mjs';
+import { redactSensitiveContent, redactSensitiveMessage, redactSensitiveToolCall } from '../sensitive-projection.mjs';
 import { promptContentText } from './prompt-utils.mjs';
 
 const TURN_CHECKPOINT_VERSION = 1;
@@ -96,7 +98,7 @@ export function checkpointMessage(message) {
   return content === message.content ? message : { ...message, content };
 }
 
-export function matchingUserMessage(message, currentUserContent) {
+function matchingUserMessage(message, currentUserContent) {
   return (
     message?.role === 'user' &&
     (message.content === currentUserContent ||
@@ -131,16 +133,54 @@ export function emptyInterruptionSnapshot() {
   };
 }
 
-// ── Header (write-once, atomic) ─────────────────────────────────────────────
+// Observed tool calls ([id, { call, eagerStarted }]) and early tool results
+// ([id, tool message]) as a checkpoint stores them (sensitive-projection.mjs).
+const storedCallEntries = (sessionId, entries) =>
+  entries.map(([id, entry]) => {
+    const call = redactSensitiveToolCall(sessionId, entry?.call);
+    return [id, call === entry?.call ? entry : { ...entry, call }];
+  });
+const storedResultEntries = (sessionId, entries) =>
+  entries.map(([id, message]) => [id, redactSensitiveMessage(sessionId, message)]);
+
+/** Interruption snapshot `snapshot` as `sessionId`'s checkpoint stores it:
+ *  sensitive values (sensitive-values.mjs) replaced, and of the partial text
+ *  only what no value can still complete. */
+function redactInterruptionSnapshot(sessionId, snapshot) {
+  const source = snapshot ?? emptyInterruptionSnapshot();
+  if (!sensitiveValuesVersion(sessionId)) return source;
+  return {
+    ...source,
+    partialAssistantContent: redactSettledText(sessionId, String(source.partialAssistantContent || '')),
+    partialReasoningContent: redactSettledText(sessionId, String(source.partialReasoningContent || '')),
+    observedToolCalls: storedCallEntries(
+      sessionId,
+      Array.isArray(source.observedToolCalls) ? source.observedToolCalls : []
+    ),
+    observedToolResults: storedResultEntries(
+      sessionId,
+      Array.isArray(source.observedToolResults) ? source.observedToolResults : []
+    ),
+  };
+}
+
+// ── Header (written once per turn, again when a sensitive value is marked) ──
 
 export function writeCheckpointHeader(checkpoint) {
-  const target = turnCheckpointPath(checkpoint.sessionId);
+  const { sessionId } = checkpoint;
+  const target = turnCheckpointPath(sessionId);
   const payload = {
     ...checkpoint,
     version: TURN_CHECKPOINT_VERSION,
-    currentUserContent: sanitizeContentForStoredHistory(checkpoint.currentUserContent),
-    turnMessages: (Array.isArray(checkpoint.turnMessages) ? checkpoint.turnMessages : []).map(checkpointMessage),
-    interruption: checkpoint.interruption ?? emptyInterruptionSnapshot(),
+    currentUserContent: redactSensitiveContent(
+      sessionId,
+      sanitizeContentForStoredHistory(checkpoint.currentUserContent)
+    ),
+    turnMessages: (Array.isArray(checkpoint.turnMessages) ? checkpoint.turnMessages : []).map((message) =>
+      redactSensitiveMessage(sessionId, checkpointMessage(message))
+    ),
+    interruption: redactInterruptionSnapshot(sessionId, checkpoint.interruption),
+    // Counts, token readings and signatures only: no text.
     contextState: checkpoint.contextState ?? null,
     updatedAt: Date.now(),
   };
@@ -488,7 +528,15 @@ export function replayTurnJournal(header) {
     if (seq > expected) break;
     expected = seq + 1;
     if (!head) {
-      if (record.t !== 'h' || record.turnToken !== header.turnToken) return header;
+      // A header rewritten for a newly marked sensitive value starts a new
+      // journal epoch; the journal it replaces never replays onto it.
+      if (
+        record.t !== 'h' ||
+        record.turnToken !== header.turnToken ||
+        (Number(record.e) || 0) !== (Number(header.journalEpoch) || 0)
+      ) {
+        return header;
+      }
       head = true;
       continue;
     }
@@ -529,7 +577,7 @@ export function replayTurnJournal(header) {
  * turn-relative index) plus an opaque interruption cursor, so each encode()
  * touches only what changed since the previous flush.
  */
-export function createTurnJournalEncoder({ turnToken } = {}) {
+export function createTurnJournalEncoder({ turnToken, sessionId = null } = {}) {
   let journaled = [];
   let fullTranscript = false;
   let cursor = null;
@@ -537,27 +585,65 @@ export function createTurnJournalEncoder({ turnToken } = {}) {
   // Per-turn record sequence. It is assigned where records are produced, so
   // the number line is exactly the enqueue order the write lane preserves.
   let seq = 0;
+  // Set while the session has sensitive values (sensitive-values.mjs): the
+  // tracker's state as its deltas build it (`raw`) and the state the journal
+  // replays to (`written`). Interruption deltas are then journaled as the
+  // difference of the redacted text, so a value that streams in across
+  // flushes never lands in pieces. A newly marked value reseeds the encoder
+  // (turn-checkpoint.mjs), so the session's values are known whenever this is null.
+  let mirror = null;
   const line = (record) => {
     const stamped = { ...record, s: seq };
     seq += 1;
     return `${JSON.stringify(stamped)}\n`;
   };
+  const stored = (message) => redactSensitiveMessage(sessionId, checkpointMessage(message));
+  const interruptionRecord = (delta) => {
+    if (!mirror) return delta;
+    applyInterruptionDelta(mirror.raw, delta);
+    const out = {};
+    for (const key of ['rs', 'ph', 'cc', 'od']) if (Object.hasOwn(delta, key)) out[key] = delta[key];
+    for (const [field, setKey, appendKey] of [
+      ['text', 'ts', 'ta'],
+      ['reasoning', 'qs', 'qa'],
+    ]) {
+      const settled = redactSettledText(sessionId, mirror.raw[field]);
+      const written = mirror.written[field];
+      if (settled === written) continue;
+      if (settled.startsWith(written)) out[appendKey] = settled.slice(written.length);
+      else out[setKey] = settled;
+    }
+    if (Object.hasOwn(delta, 'tb')) out.tb = redactSensitiveContent(sessionId, mirror.raw.tomb);
+    if (delta.cs) out.cs = storedCallEntries(sessionId, delta.cs);
+    if (delta.os) out.os = storedResultEntries(sessionId, delta.os);
+    applyInterruptionDelta(mirror.written, out);
+    return out;
+  };
   return {
     /** Seed from the turn's opening state; returns the header's messages
      * and the journal's opening lines (head record, plus — defensively —
      * the delta that makes the journal authoritative if the tracker already
-     * carried state at open time). */
-    seed(turnOutgoing, currentUserContent, interruption, contextState = null) {
+     * carried state at open time). `snapshot` is the tracker snapshot the
+     * header stores; `epoch` names the journal a rewritten header starts. */
+    seed(turnOutgoing, currentUserContent, interruption, contextState = null, { snapshot = null, epoch = 0 } = {}) {
       const source = Array.isArray(turnOutgoing) ? turnOutgoing : [];
       const start = findTurnStart(source, currentUserContent);
       fullTranscript = start < 0;
       journaled = fullTranscript ? source.slice() : source.slice(start);
+      mirror = sensitiveValuesVersion(sessionId)
+        ? {
+            raw: interruptionStateFromSnapshot(snapshot),
+            written: interruptionStateFromSnapshot(redactInterruptionSnapshot(sessionId, snapshot)),
+          }
+        : null;
       const seeded = typeof interruption?.journalDelta === 'function' ? interruption.journalDelta(null) : null;
       cursor = seeded ? seeded.cursor : null;
       contextStateKey = contextState == null ? null : JSON.stringify(contextState);
       seq = 0;
-      const openLines = [line({ t: 'h', turnToken, at: Date.now() })];
-      if (seeded?.changed) openLines.push(line({ t: 'x', d: seeded.delta, at: Date.now() }));
+      const openLines = [line({ t: 'h', turnToken, ...(epoch ? { e: epoch } : {}), at: Date.now() })];
+      const seededDelta = seeded?.changed ? interruptionRecord(seeded.delta) : null;
+      if (seededDelta && Object.keys(seededDelta).length)
+        openLines.push(line({ t: 'x', d: seededDelta, at: Date.now() }));
       return {
         turnMessages: journaled.map(checkpointMessage),
         fullTranscript,
@@ -579,7 +665,7 @@ export function createTurnJournalEncoder({ turnToken } = {}) {
         journaled = source.slice();
         records.push({
           t: 'full',
-          ms: journaled.map(checkpointMessage),
+          ms: journaled.map(stored),
         });
       } else {
         const offset = fullTranscript ? 0 : start;
@@ -588,7 +674,7 @@ export function createTurnJournalEncoder({ turnToken } = {}) {
           const raw = source[offset + index];
           if (journaled[index] === raw) continue;
           journaled[index] = raw;
-          records.push({ t: 'm', i: index, m: checkpointMessage(raw) });
+          records.push({ t: 'm', i: index, m: stored(raw) });
         }
         if (journaled.length > length) {
           journaled.length = length;
@@ -598,7 +684,8 @@ export function createTurnJournalEncoder({ turnToken } = {}) {
       if (typeof interruption?.journalDelta === 'function') {
         const next = interruption.journalDelta(cursor);
         cursor = next.cursor;
-        if (next.changed) records.push({ t: 'x', d: next.delta });
+        const delta = next.changed ? interruptionRecord(next.delta) : null;
+        if (delta && Object.keys(delta).length) records.push({ t: 'x', d: delta });
       }
       const nextContextStateKey = contextState == null ? null : JSON.stringify(contextState);
       if (nextContextStateKey !== contextStateKey) {

package/src/runtime/agent/orchestrator/session/manager/turn-checkpoint.mjs

@@ -19,6 +19,7 @@ import {
 } from './turn-checkpoint-journal.mjs';
 import { captureTurnCheckpointContextState, restoreTurnCheckpointContextState } from './turn-checkpoint-context.mjs';
 import { stripProviderReplayMessages } from './provider-replay.mjs';
+import { sensitiveValuesVersion } from '../sensitive-values.mjs';
 
 export { turnCheckpointPath, turnMessagesForCheckpoint };
 export { captureTurnCheckpointContextState, restoreTurnCheckpointContextState };
@@ -67,9 +68,14 @@ export function projectTurnCheckpointMessages(session, checkpoint) {
 // long tool-heavy turn no longer amplifies into the shared engine thread that
 // every fanned-out agent session shares.
 export function createTurnCheckpointRecorder({ sessionId, generation, turnToken, startedAt }) {
-  const encoder = createTurnJournalEncoder({ turnToken });
+  const encoder = createTurnJournalEncoder({ turnToken, sessionId });
   let opened = false;
   let stopped = false;
+  // The sensitive-values version (sensitive-values.mjs) the header and
+  // journal were written under. A newly marked value rewrites both from the
+  // turn's current state with the value replaced, under a new journal epoch,
+  // so no recovery record keeps it.
+  let openedVersion = 0;
   return {
     get opened() {
       return opened;
@@ -77,8 +83,14 @@ export function createTurnCheckpointRecorder({ sessionId, generation, turnToken,
     /** True when this call wrote or queued durable state. */
     record({ currentUserContent, turnOutgoing, interruption, contextState = null }) {
       if (stopped || !sessionId || !turnToken) return false;
-      if (!opened) {
-        const seed = encoder.seed(turnOutgoing, currentUserContent, interruption, contextState);
+      const version = sensitiveValuesVersion(sessionId);
+      if (!opened || version !== openedVersion) {
+        const snapshot =
+          typeof interruption?.snapshot === 'function' ? interruption.snapshot() : emptyInterruptionSnapshot();
+        const seed = encoder.seed(turnOutgoing, currentUserContent, interruption, contextState, {
+          snapshot,
+          epoch: version,
+        });
         writeCheckpointHeader({
           sessionId,
           generation,
@@ -87,10 +99,11 @@ export function createTurnCheckpointRecorder({ sessionId, generation, turnToken,
           currentUserContent,
           turnMessages: seed.turnMessages,
           ...(seed.fullTranscript ? { fullTranscript: true } : {}),
-          interruption:
-            typeof interruption?.snapshot === 'function' ? interruption.snapshot() : emptyInterruptionSnapshot(),
+          ...(version ? { journalEpoch: version } : {}),
+          interruption: snapshot,
           contextState: seed.contextState,
         });
+        openedVersion = version;
         // Opening the journal is part of the anchor: a leftover journal
         // from an earlier turn of this session must never replay onto
         // the new header. It lands synchronously when the lane is idle
@@ -211,6 +224,9 @@ export function recoverTurnCheckpoint(session) {
   // mark it unanchored so the first resumed send cannot compact from a gross
   // whole-transcript estimate.
   const contextStateRestored = restoreTurnCheckpointContextState(session, checkpoint);
+  // Diagnostic only (anthropic-prefix-trace.mjs): the turn's last settled
+  // request, whatever the context reading's alignment.
+  if (checkpoint.contextState?.prefixBaseline) session.providerPrefixBaseline = checkpoint.contextState.prefixBaseline;
   delete session.activeTurnCheckpoint;
   delete session.providerState;
   delete session._providerPrefixGuardState;

package/src/runtime/agent/orchestrator/session/manager/turn-interruption.mjs

@@ -110,6 +110,15 @@ function finalizeInterruptedTurn({
     };
   }
 
+  // Killed with a request on the wire (phase 'streaming' after a tool run):
+  // the provider received the transcript up to its last message, and may
+  // have cached it. Stamping that message keeps what this interruption
+  // appends (the marker, the next prompt) out of the tool_result it ends —
+  // see toAnthropicMessages. The stamp is meta only; no wire bytes change.
+  const sentTail = messages.length - 1;
+  if (phase === 'streaming' && (messages[sentTail]?.role === 'tool' || messages[sentTail]?.role === 'user')) {
+    messages[sentTail] = { ...messages[sentTail], meta: { ...messages[sentTail].meta, sentRequestTail: true } };
+  }
   appendObservedTurnOutput(messages, {
     partialAssistantContent,
     partialReasoningContent,

package/src/runtime/agent/orchestrator/session/pre-send-compact.mjs

@@ -30,7 +30,7 @@ import { traceAgentCompact, messagePrefixHash } from '../agent-trace.mjs';
 import { invalidateProviderRequestToolsScope } from '../runtime-core/provider-request-tools.mjs';
 import { bumpUsageMetricsEpoch } from './manager/usage-metrics.mjs';
 import { resetReadStateAfterCompaction } from './read-dedup.mjs';
-import { scheduleCompactionArchive, stampCompactionMessageIds } from './compaction-archive-capture.mjs';
+import { prepareCompactionArchive, stampCompactionMessageIds } from './compaction-archive-capture.mjs';
 import { writeStderrBestEffort } from '../../../shared/best-effort-stderr.mjs';
 import { isAgentModeSession } from './agent-mode.mjs';
 import { applyPendingWorkspaceReroot } from './manager/prompt-utils.mjs';
@@ -92,7 +92,11 @@ function preSendCompactDecision(state, compactPolicy) {
     messages,
     sessionRef,
   });
-  const cacheExpired = shouldCompactForExpiredAgentCache(sessionRef, state.opts);
+  const cacheExpired = shouldCompactForExpiredAgentCache(sessionRef, state.opts, {
+    provider: sessionRef?.provider || state.provider?.name,
+    model: state.model,
+    messages,
+  });
   const mediaPressure = shouldCompactForRequestMedia(messages, sessionRef?.provider);
   const requireReduction = !reactivePending && !mediaPressure;
   let shouldCompact =
@@ -409,19 +413,31 @@ function adoptCompactedTranscript(ctx, run) {
   const { messages, sessionRef, sessionId, opts } = state;
   const replaced = messages.slice();
   if (sessionRef) backfillFallbackSessionTitle(sessionRef, replaced);
+  // Display-only archive of the dropped conversation, made durable (pending
+  // sidecar) BEFORE the shortened transcript is adopted and can be saved; a
+  // sidecar that cannot be written keeps the old transcript and fails this
+  // compaction. The publication runs off this synchronous adoption.
+  let prepared = null;
+  if (sessionRef) {
+    try {
+      prepared = prepareCompactionArchive({ session: sessionRef, sessionId, before: replaced, after: run.compacted });
+    } catch (archiveError) {
+      throwCompactFailure(ctx, run, archiveError);
+    }
+  }
   messages.length = 0;
   messages.push(...run.compacted);
-  // Display-only archive of the dropped conversation; the projection and the
-  // write run off this synchronous adoption.
-  const archived = sessionRef
-    ? scheduleCompactionArchive({ session: sessionRef, sessionId, before: replaced, after: messages })
-    : null;
+  const archived = prepared ? { ...prepared, written: prepared.start() } : null;
   ctx.droppedMessages = archived?.dropped ?? 0;
   ctx.droppedIdentities = archived?.identities ?? null;
   acknowledgeGoalReminder(sessionRef, run);
   // The compacted transcript breaks the cache anyway: a staged working-folder
   // change re-roots the system prompt now and needs no notice any more.
   if (sessionRef) applyPendingWorkspaceReroot(sessionRef, messages);
+  // The system prompt is rebuilt from current sources outside a running turn
+  // (session-runtime agent-profile-fold.mjs): the next cold point folds it in
+  // instead of adding a break to the turn that is already warm again.
+  if (sessionRef) sessionRef.promptFoldPending = true;
   resetReadStateAfterCompaction(sessionId);
   // Cross-turn receipts reference tool results that compaction just removed
   // from context; a stub for them would point at nothing. Clear in place so
@@ -444,8 +460,7 @@ function adoptCompactedTranscript(ctx, run) {
   ctx.providerStateCleared = true;
   // Compaction starts a new loop epoch: the iteration counter restarts at 0
   // so iteration indices (traces, usage metrics, cross-turn dedup windows)
-  // count from the compacted transcript. The counter bounds nothing — the
-  // loop has no iteration cap.
+  // count from the compacted transcript.
   ctx.iterations = 0;
   // New loop epoch so persistIterationMetrics idempotency keys do not
   // collide when iteration indices restart at 1 (incl. iter 1 → iter 1).

package/src/runtime/agent/orchestrator/session/prompt-cache-idle-gaps.mjs

@@ -0,0 +1,113 @@
+// prompt-cache-idle-gaps.mjs — per session, the idle gaps the cache warmer
+// learns from (cache-warm.mjs): from the send of the session's last real
+// request (when it used the cache) to its next real request. Kept beside the
+// prompt-cache touch store, never in the session record. A gap is kept as
+// `{ at, ms }`, or `{ at, ms, censored: true }` when the session was still
+// idle at the window it was cut at. The session's open gap (`open`: its
+// start) survives a restart. Gaps older than the lookback are pruned on
+// write; a deleted session's entry is dropped.
+import { join } from 'node:path';
+import { readJsonStateSync, writeJsonAtomicAsync } from '../../../shared/atomic-file.mjs';
+import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
+
+const PROMPT_CACHE_IDLE_GAP_FILE = 'prompt-cache-idle-gaps.json';
+
+const validGap = (gap) => gap && Number(gap.at) > 0 && Number(gap.ms) > 0;
+
+/**
+ * An idle-gap store backed by `path` (default: the data dir's file).
+ * `lookbackMs`: how long gaps are kept; `windowMs`: a gap reaching it is
+ * recorded as censored there; `minMs`: shorter gaps are not kept (no
+ * refresh point lies inside them).
+ */
+export function createIdleGapStore({
+  path = () => join(resolvePluginData(), PROMPT_CACHE_IDLE_GAP_FILE),
+  lookbackMs,
+  windowMs,
+  minMs,
+  now = () => Date.now(),
+  log = (line) => process.stderr.write(`[cache-warm] ${line}\n`),
+} = {}) {
+  let sessions = null;
+  let writing = Promise.resolve();
+  const filePath = () => (typeof path === 'function' ? path() : path);
+  const load = () => {
+    if (sessions) return sessions;
+    sessions = new Map();
+    const stored = readJsonStateSync(filePath(), { fallback: null });
+    for (const [sessionId, entry] of Object.entries(stored?.sessions || {})) {
+      const gaps = Array.isArray(entry?.gaps)
+        ? entry.gaps.filter(validGap).map((gap) => {
+            const item = { at: Number(gap.at), ms: Number(gap.ms) };
+            if (gap.censored) item.censored = true;
+            return item;
+          })
+        : [];
+      const open = Number(entry?.open) > 0 ? Number(entry.open) : 0;
+      if (gaps.length || open) sessions.set(sessionId, { open, gaps });
+    }
+    return sessions;
+  };
+  const entryOf = (sessionId) => {
+    const id = String(sessionId || '');
+    if (!load().has(id)) sessions.set(id, { open: 0, gaps: [] });
+    return sessions.get(id);
+  };
+  const flush = () => {
+    const since = now() - lookbackMs;
+    const out = {};
+    for (const [sessionId, entry] of load()) {
+      entry.gaps = entry.gaps.filter((gap) => gap.at >= since);
+      if (entry.open && entry.open < since) entry.open = 0;
+      if (!entry.gaps.length && !entry.open) sessions.delete(sessionId);
+      else out[sessionId] = { ...(entry.open ? { open: entry.open } : {}), gaps: entry.gaps };
+    }
+    writing = writing
+      .catch(() => {})
+      .then(() => writeJsonAtomicAsync(filePath(), { version: 1, sessions: out }, { compact: true }));
+    return writing;
+  };
+  // A failed write is reported; the next flush recovers the queue and writes.
+  const scheduleFlush = () =>
+    void flush().catch((err) => log(`idle-gap store write failed (${filePath()}): ${err?.message || err}`));
+  return {
+    /** The session went idle: its last real request used the cache at `at`. */
+    open(sessionId, at) {
+      if (!sessionId || !(Number(at) > 0)) return;
+      entryOf(sessionId).open = Number(at);
+      scheduleFlush();
+    },
+    /** A real request arrived at `at`: close the open gap as a return, or as
+     *  censored at the window when it outlasted it. Resolves the kept gap or
+     *  null (none open, or too short to keep). */
+    close(sessionId, at) {
+      const entry = sessionId ? load().get(String(sessionId)) : null;
+      if (!entry?.open) return null;
+      const start = entry.open;
+      entry.open = 0;
+      const ms = Number(at) - start;
+      let gap = null;
+      if (ms >= windowMs) gap = { at: start, ms: windowMs, censored: true };
+      else if (ms > minMs) gap = { at: start, ms };
+      if (gap) entry.gaps.push(gap);
+      scheduleFlush();
+      return gap;
+    },
+    /** The session's kept gaps of the lookback (oldest first). */
+    gaps(sessionId) {
+      const since = now() - lookbackMs;
+      const entry = sessionId ? load().get(String(sessionId)) : null;
+      return (entry?.gaps || []).filter((gap) => gap.at >= since).map((gap) => ({ ...gap }));
+    },
+    /** When the session's open gap started, or 0. */
+    openAt(sessionId) {
+      return (sessionId && load().get(String(sessionId))?.open) || 0;
+    },
+    /** The session is gone (deleted): drop everything it learned. */
+    forget(sessionId) {
+      if (sessionId && load().delete(String(sessionId))) scheduleFlush();
+    },
+    /** Write pending changes now (tests, shutdown). */
+    flush,
+  };
+}

package/src/runtime/agent/orchestrator/session/prompt-cache-touch-store.mjs

@@ -0,0 +1,150 @@
+// prompt-cache-touch-store.mjs — the durable record cache warms re-arm from
+// after a restart (cache-warm.mjs): per session, the last confirmed touch of
+// its cached prefix — when a call whose usage showed a read or write on it was
+// sent, the tier the provider reported writing, the account that holds it and
+// the prompt size. Kept beside the session records, never in them: a warm's
+// touch must not move a session's own timestamps (activity, autoClear).
+// Expired entries are dropped on write.
+//
+// Beside the touches: per session, when a warm last used the cache
+// successfully (a read with no write). The idle auto-clear measures idleness
+// from it (idle-auto-clear-gate.mjs) until a real request settles, so it
+// outlives the touch: a later miss or an expiry drops the touch, not the use.
+import { join } from 'node:path';
+import { readJsonStateSync, writeJsonAtomicAsync } from '../../../shared/atomic-file.mjs';
+import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
+
+const PROMPT_CACHE_TOUCH_FILE = 'prompt-cache-touches.json';
+
+function validTouch(value) {
+  return (
+    value &&
+    typeof value === 'object' &&
+    Number(value.touchAt) > 0 &&
+    Number(value.ttlMs) > 0 &&
+    Number(value.promptTokens) > 0
+  );
+}
+
+// A warm use as stored: `{ at, provider, model, accountId }` — the route and
+// account whose cached prefix the warm read. A bare time (written before the
+// identity was recorded) keeps its time and matches no route.
+function warmUseRecord(value) {
+  const record = value && typeof value === 'object' ? value : { at: value };
+  if (!(Number(record.at) > 0)) return null;
+  return {
+    at: Number(record.at),
+    provider: String(record.provider || ''),
+    model: String(record.model || ''),
+    accountId: String(record.accountId || ''),
+  };
+}
+
+/** A touch store backed by `path` (default: the data dir's file). */
+export function createPromptCacheTouchStore(
+  path = () => join(resolvePluginData(), PROMPT_CACHE_TOUCH_FILE),
+  { log = (line) => process.stderr.write(`[cache-warm] ${line}\n`) } = {}
+) {
+  let touches = null;
+  let warmUses = null;
+  let writing = Promise.resolve();
+  const filePath = () => (typeof path === 'function' ? path() : path);
+  const load = () => {
+    if (touches) return touches;
+    touches = new Map();
+    warmUses = new Map();
+    const stored = readJsonStateSync(filePath(), { fallback: null });
+    for (const [sessionId, touch] of Object.entries(stored?.touches || {})) {
+      if (validTouch(touch)) touches.set(sessionId, { ...touch });
+    }
+    for (const [sessionId, use] of Object.entries(stored?.warmUses || {})) {
+      const record = warmUseRecord(use);
+      if (record) warmUses.set(sessionId, record);
+    }
+    return touches;
+  };
+  const uses = () => {
+    load();
+    return warmUses;
+  };
+  // Touches change once per real request or warm: each change is written at
+  // once, the writes serialized.
+  const flush = () => {
+    const now = Date.now();
+    const out = {};
+    for (const [sessionId, touch] of load()) {
+      if (touch.touchAt + touch.ttlMs > now) out[sessionId] = touch;
+      else touches.delete(sessionId);
+    }
+    writing = writing
+      .catch(() => {})
+      .then(() =>
+        writeJsonAtomicAsync(
+          filePath(),
+          { version: 1, touches: out, warmUses: Object.fromEntries(uses()) },
+          { compact: true }
+        )
+      );
+    return writing;
+  };
+  // A failed write is reported; the next flush recovers the queue and writes.
+  const scheduleFlush = () =>
+    void flush().catch((err) => log(`touch store write failed (${filePath()}): ${err?.message || err}`));
+  return {
+    /** The session's last confirmed touch, or null. */
+    get(sessionId) {
+      const touch = load().get(String(sessionId || ''));
+      return touch ? { ...touch } : null;
+    },
+    /** The sessions holding a touch. */
+    ids() {
+      return [...load().keys()];
+    },
+    /** Record a confirmed touch `{ touchAt, ttlMs, accountId, promptTokens }`. */
+    record(sessionId, touch) {
+      if (!sessionId || !validTouch(touch)) return;
+      load().set(String(sessionId), {
+        touchAt: Number(touch.touchAt),
+        ttlMs: Number(touch.ttlMs),
+        promptTokens: Number(touch.promptTokens),
+        ...(touch.accountId ? { accountId: String(touch.accountId) } : {}),
+      });
+      scheduleFlush();
+    },
+    /** The session's cached prefix is gone (compaction, clear, close, miss). */
+    forget(sessionId) {
+      if (load().delete(String(sessionId || ''))) scheduleFlush();
+    },
+    /** When a warm last used the session's cache successfully, or 0. */
+    lastWarmUse(sessionId) {
+      return uses().get(String(sessionId || ''))?.at || 0;
+    },
+    /** The session's last successful warm use `{ at, provider, model,
+     *  accountId }`, or null. */
+    warmUse(sessionId) {
+      const use = uses().get(String(sessionId || ''));
+      return use ? { ...use } : null;
+    },
+    /** A warm read the session's cache without writing at `at`, on the
+     *  route and account `{ provider, model, accountId }`. */
+    recordWarmUse(sessionId, at, identity = {}) {
+      const record = warmUseRecord({ ...identity, at });
+      if (!sessionId || !record) return;
+      uses().set(String(sessionId), record);
+      scheduleFlush();
+    },
+    /** The session's own activity supersedes its warm use (a real request
+     *  settled) or its cached conversation is gone (compaction, clear). */
+    forgetWarmUse(sessionId) {
+      if (uses().delete(String(sessionId || ''))) scheduleFlush();
+    },
+    /** Write pending changes now (tests, shutdown). */
+    flush,
+  };
+}
+
+let defaultStore = null;
+export function promptCacheTouchStore() {
+  defaultStore ??= createPromptCacheTouchStore();
+  return defaultStore;
+}