@ouro.bot/cli 0.1.0-alpha.21 → 0.1.0-alpha.210

package/dist/mind/context.js

@@ -36,7 +36,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.trimMessages = trimMessages;
 exports.validateSessionMessages = validateSessionMessages;
 exports.repairSessionMessages = repairSessionMessages;
+exports.migrateToolNames = migrateToolNames;
 exports.saveSession = saveSession;
+exports.appendSyntheticAssistantMessage = appendSyntheticAssistantMessage;
 exports.loadSession = loadSession;
 exports.postTurn = postTurn;
 exports.deleteSession = deleteSession;
@@ -50,17 +52,17 @@ function buildTrimmableBlocks(messages) {
     let i = 0;
     while (i < messages.length) {
         const msg = messages[i];
-        if (msg?.role === "system") {
+        if (msg.role === "system") {
             i++;
             continue;
         }
         // Tool coherence block: assistant message with tool_calls + immediately following tool results
-        if (msg?.role === "assistant" && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) {
+        if (msg.role === "assistant" && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) {
             const indices = [i];
             i++;
             while (i < messages.length) {
                 const next = messages[i];
-                if (next?.role !== "tool")
+                if (next.role !== "tool")
                     break;
                 indices.push(i);
                 i++;
@@ -78,13 +80,13 @@ function buildTrimmableBlocks(messages) {
 function getSystemMessageIndices(messages) {
     const indices = [];
     for (let i = 0; i < messages.length; i++) {
-        if (messages[i]?.role === "system")
+        if (messages[i].role === "system")
             indices.push(i);
     }
     return indices;
 }
 function buildTrimmedMessages(messages, kept) {
-    return messages.filter((m, idx) => m?.role === "system" || kept.has(idx));
+    return messages.filter((m, idx) => m.role === "system" || kept.has(idx));
 }
 function trimMessages(messages, maxTokens, contextMargin, actualTokenCount) {
     const targetTokens = Math.floor(maxTokens * (1 - contextMargin / 100));
@@ -132,7 +134,7 @@ function trimMessages(messages, maxTokens, contextMargin, actualTokenCount) {
     let remaining = actualTokenCount;
     const kept = new Set();
     for (let i = 0; i < messages.length; i++) {
-        if (messages[i]?.role !== "system")
+        if (messages[i].role !== "system")
             kept.add(i);
     }
     // Drop oldest blocks until we fall under target.
@@ -146,7 +148,7 @@ function trimMessages(messages, maxTokens, contextMargin, actualTokenCount) {
     let trimmed = buildTrimmedMessages(messages, kept);
     // If we're still above budget after dropping everything trimmable, preserve system only.
     if (remaining > targetTokens) {
-        trimmed = messages.filter((m) => m?.role === "system");
+        trimmed = messages.filter((m) => m.role === "system");
     }
     const estimatedAfter = (0, token_estimate_1.estimateTokensForMessages)(trimmed);
     (0, runtime_1.emitNervesEvent)({
@@ -219,7 +221,7 @@ function repairSessionMessages(messages) {
         result.push(msg);
     }
     (0, runtime_1.emitNervesEvent)({
-        level: "warn",
+        level: "info",
         event: "mind.session_invariant_repair",
         component: "mind",
         message: "repaired session invariant violations",
@@ -227,11 +229,79 @@ function repairSessionMessages(messages) {
     });
     return result;
 }
-function saveSession(filePath, messages, lastUsage) {
+function stripOrphanedToolResults(messages) {
+    const validCallIds = new Set();
+    for (const msg of messages) {
+        if (msg.role !== "assistant" || !Array.isArray(msg.tool_calls))
+            continue;
+        for (const toolCall of msg.tool_calls)
+            validCallIds.add(toolCall.id);
+    }
+    let removed = 0;
+    const repaired = messages.filter((msg) => {
+        if (msg.role !== "tool")
+            return true;
+        const keep = validCallIds.has(msg.tool_call_id);
+        if (!keep)
+            removed++;
+        return keep;
+    });
+    if (removed > 0) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "info",
+            event: "mind.session_orphan_tool_result_repair",
+            component: "mind",
+            message: "removed orphaned tool results from session history",
+            meta: { removed },
+        });
+    }
+    return repaired;
+}
+// Tool renames that have shipped. Old names in session history confuse the
+// model into calling tools that no longer exist. Applied on session load so
+// the transcript uses the current vocabulary.
+const TOOL_NAME_MIGRATIONS = {
+    final_answer: "settle",
+    no_response: "observe",
+    go_inward: "ponder",
+    descend: "ponder",
+    memory_save: "diary_write",
+    memory_search: "recall",
+};
+function migrateToolNames(messages) {
+    let migrated = 0;
+    const result = messages.map((msg) => {
+        if (msg.role !== "assistant" || !Array.isArray(msg.tool_calls) || msg.tool_calls.length === 0)
+            return msg;
+        let changed = false;
+        const updatedCalls = msg.tool_calls.map((tc) => {
+            if (tc.type !== "function")
+                return tc;
+            const newName = TOOL_NAME_MIGRATIONS[tc.function.name];
+            if (!newName)
+                return tc;
+            changed = true;
+            migrated++;
+            return { ...tc, function: { ...tc.function, name: newName } };
+        });
+        return changed ? { ...msg, tool_calls: updatedCalls } : msg;
+    });
+    if (migrated > 0) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "info",
+            event: "mind.session_tool_name_migration",
+            component: "mind",
+            message: "migrated deprecated tool names in session history",
+            meta: { migrated },
+        });
+    }
+    return result;
+}
+function saveSession(filePath, messages, lastUsage, state) {
     const violations = validateSessionMessages(messages);
     if (violations.length > 0) {
         (0, runtime_1.emitNervesEvent)({
-            level: "warn",
+            level: "info",
             event: "mind.session_invariant_violation",
             component: "mind",
             message: "session invariant violated on save",
@@ -239,12 +309,41 @@ function saveSession(filePath, messages, lastUsage) {
         });
         messages = repairSessionMessages(messages);
     }
+    messages = stripOrphanedToolResults(messages);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     const envelope = { version: 1, messages };
     if (lastUsage)
         envelope.lastUsage = lastUsage;
+    if (state?.mustResolveBeforeHandoff === true || typeof state?.lastFriendActivityAt === "string") {
+        envelope.state = {
+            ...(state?.mustResolveBeforeHandoff === true ? { mustResolveBeforeHandoff: true } : {}),
+            ...(typeof state?.lastFriendActivityAt === "string" ? { lastFriendActivityAt: state.lastFriendActivityAt } : {}),
+        };
+    }
     fs.writeFileSync(filePath, JSON.stringify(envelope, null, 2));
 }
+function appendSyntheticAssistantMessage(filePath, content) {
+    try {
+        if (!fs.existsSync(filePath))
+            return false;
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.version !== 1 || !Array.isArray(data.messages))
+            return false;
+        data.messages.push({ role: "assistant", content });
+        fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+        (0, runtime_1.emitNervesEvent)({
+            component: "mind",
+            event: "mind.session_synthetic_message_appended",
+            message: "appended synthetic assistant message to session",
+            meta: { path: filePath, contentLength: content.length },
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function loadSession(filePath) {
     try {
         const raw = fs.readFileSync(filePath, "utf-8");
@@ -255,7 +354,7 @@ function loadSession(filePath) {
         const violations = validateSessionMessages(messages);
         if (violations.length > 0) {
             (0, runtime_1.emitNervesEvent)({
-                level: "warn",
+                level: "info",
                 event: "mind.session_invariant_violation",
                 component: "mind",
                 message: "session invariant violated on load",
@@ -263,13 +362,25 @@ function loadSession(filePath) {
             });
             messages = repairSessionMessages(messages);
         }
-        return { messages, lastUsage: data.lastUsage };
+        messages = stripOrphanedToolResults(messages);
+        messages = migrateToolNames(messages);
+        const rawState = data?.state && typeof data.state === "object" && data.state !== null
+            ? data.state
+            : undefined;
+        const state = rawState && (rawState.mustResolveBeforeHandoff === true
+            || typeof rawState.lastFriendActivityAt === "string")
+            ? {
+                ...(rawState.mustResolveBeforeHandoff === true ? { mustResolveBeforeHandoff: true } : {}),
+                ...(typeof rawState.lastFriendActivityAt === "string" ? { lastFriendActivityAt: rawState.lastFriendActivityAt } : {}),
+            }
+            : undefined;
+        return { messages, lastUsage: data.lastUsage, state };
     }
     catch {
         return null;
     }
 }
-function postTurn(messages, sessPath, usage, hooks) {
+function postTurn(messages, sessPath, usage, hooks, state) {
     if (hooks?.beforeTrim) {
         try {
             hooks.beforeTrim([...messages]);
@@ -289,7 +400,7 @@ function postTurn(messages, sessPath, usage, hooks) {
     const { maxTokens, contextMargin } = (0, config_1.getContextConfig)();
     const trimmed = trimMessages(messages, maxTokens, contextMargin, usage?.input_tokens);
     messages.splice(0, messages.length, ...trimmed);
-    saveSession(sessPath, messages, usage);
+    saveSession(sessPath, messages, usage, state);
 }
 function deleteSession(filePath) {
     try {

package/dist/mind/{memory.js → diary.js}

@@ -33,20 +33,23 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.__memoryTestUtils = void 0;
-exports.ensureMemoryStorePaths = ensureMemoryStorePaths;
-exports.appendFactsWithDedup = appendFactsWithDedup;
-exports.readMemoryFacts = readMemoryFacts;
-exports.saveMemoryFact = saveMemoryFact;
+exports.ensureDiaryStorePaths = ensureDiaryStorePaths;
+exports.appendEntriesWithDedup = appendEntriesWithDedup;
+exports.resolveDiaryRoot = resolveDiaryRoot;
+exports.readDiaryEntries = readDiaryEntries;
+exports.saveDiaryEntry = saveDiaryEntry;
 exports.backfillEmbeddings = backfillEmbeddings;
-exports.searchMemoryFacts = searchMemoryFacts;
+exports.searchDiaryEntries = searchDiaryEntries;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const crypto_1 = require("crypto");
 const config_1 = require("../heart/config");
 const identity_1 = require("../heart/identity");
 const runtime_1 = require("../nerves/runtime");
+const sync_1 = require("../heart/sync");
+const associative_recall_1 = require("./associative-recall");
 const DEDUP_THRESHOLD = 0.6;
+const SEMANTIC_DEDUP_THRESHOLD = 0.95;
 const ENTITY_TOKEN = /[a-z0-9]+/g;
 const DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
 class OpenAIEmbeddingProvider {
@@ -78,7 +81,7 @@ class OpenAIEmbeddingProvider {
         return payload.data.map((entry) => entry.embedding);
     }
 }
-function ensureMemoryStorePaths(rootDir) {
+function ensureDiaryStorePaths(rootDir) {
     const factsPath = path.join(rootDir, "facts.jsonl");
     const entitiesPath = path.join(rootDir, "entities.json");
     const dailyDir = path.join(rootDir, "daily");
@@ -90,8 +93,8 @@ function ensureMemoryStorePaths(rootDir) {
         fs.writeFileSync(entitiesPath, "{}\n", "utf8");
     (0, runtime_1.emitNervesEvent)({
         component: "mind",
-        event: "mind.memory_paths_ready",
-        message: "memory store paths ready",
+        event: "mind.diary_paths_ready",
+        message: "diary store paths ready",
         meta: { rootDir },
     });
     return { rootDir, factsPath, entitiesPath, dailyDir };
@@ -114,15 +117,22 @@ function overlapScore(left, right) {
     }
     return common / Math.min(leftWords.size, rightWords.size);
 }
-function readExistingFacts(factsPath) {
+function readExistingEntries(factsPath) {
     if (!fs.existsSync(factsPath))
         return [];
     const raw = fs.readFileSync(factsPath, "utf8").trim();
     if (!raw)
         return [];
-    return raw
-        .split("\n")
-        .map((line) => JSON.parse(line));
+    const facts = [];
+    for (const line of raw.split("\n")) {
+        try {
+            facts.push(JSON.parse(line));
+        }
+        catch {
+            // Skip corrupt lines (e.g. partial write from a crash).
+        }
+    }
+    return facts;
 }
 function readEntityIndex(entitiesPath) {
     if (!fs.existsSync(entitiesPath))
@@ -170,13 +180,24 @@ function appendDailyFact(dailyDir, fact) {
     const dayPath = path.join(dailyDir, `${day}.jsonl`);
     fs.appendFileSync(dayPath, `${JSON.stringify(fact)}\n`, "utf8");
 }
-function appendFactsWithDedup(stores, incoming) {
-    const existing = readExistingFacts(stores.factsPath);
+function appendEntriesWithDedup(stores, incoming, options) {
+    const existing = readExistingEntries(stores.factsPath);
     const all = [...existing];
     let added = 0;
     let skipped = 0;
+    const semanticThreshold = options?.semanticThreshold;
     for (const fact of incoming) {
-        const duplicate = all.some((prior) => overlapScore(prior.text, fact.text) > DEDUP_THRESHOLD);
+        const duplicate = all.some((prior) => {
+            if (overlapScore(prior.text, fact.text) > DEDUP_THRESHOLD)
+                return true;
+            if (semanticThreshold !== undefined &&
+                Array.isArray(fact.embedding) && fact.embedding.length > 0 &&
+                Array.isArray(prior.embedding) && prior.embedding.length > 0 &&
+                fact.embedding.length === prior.embedding.length) {
+                return (0, associative_recall_1.cosineSimilarity)(fact.embedding, prior.embedding) > semanticThreshold;
+            }
+            return false;
+        });
         if (duplicate) {
             skipped++;
             continue;
@@ -184,35 +205,20 @@ function appendFactsWithDedup(stores, incoming) {
         all.push(fact);
         added++;
         fs.appendFileSync(stores.factsPath, `${JSON.stringify(fact)}\n`, "utf8");
+        (0, sync_1.trackSyncWrite)(stores.factsPath);
         updateEntityIndex(stores.entitiesPath, fact);
+        (0, sync_1.trackSyncWrite)(stores.entitiesPath);
         appendDailyFact(stores.dailyDir, fact);
+        (0, sync_1.trackSyncWrite)(path.join(stores.dailyDir, `${(fact.createdAt.slice(0, 10) || "unknown")}.jsonl`));
     }
     (0, runtime_1.emitNervesEvent)({
         component: "mind",
-        event: "mind.memory_write",
-        message: "memory write completed",
+        event: "mind.diary_write",
+        message: "diary write completed",
         meta: { added, skipped },
     });
     return { added, skipped };
 }
-function cosineSimilarity(left, right) {
-    if (left.length === 0 || right.length === 0 || left.length !== right.length)
-        return 0;
-    let dot = 0;
-    let leftNorm = 0;
-    let rightNorm = 0;
-    for (let i = 0; i < left.length; i += 1) {
-        dot += left[i] * right[i];
-        leftNorm += left[i] * left[i];
-        rightNorm += right[i] * right[i];
-    }
-    if (leftNorm === 0 || rightNorm === 0)
-        return 0;
-    return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
-}
-exports.__memoryTestUtils = {
-    cosineSimilarity,
-};
 function createDefaultEmbeddingProvider() {
     const apiKey = (0, config_1.getOpenAIEmbeddingsApiKey)().trim();
     if (!apiKey)
@@ -225,8 +231,8 @@ async function buildEmbedding(text, embeddingProvider) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
             component: "mind",
-            event: "mind.memory_embedding_unavailable",
-            message: "embedding provider unavailable for memory write",
+            event: "mind.diary_embedding_unavailable",
+            message: "embedding provider unavailable for diary write",
             meta: { reason: "missing_openai_embeddings_key" },
         });
         return [];
@@ -239,8 +245,8 @@ async function buildEmbedding(text, embeddingProvider) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
             component: "mind",
-            event: "mind.memory_embedding_unavailable",
-            message: "embedding provider unavailable for memory write",
+            event: "mind.diary_embedding_unavailable",
+            message: "embedding provider unavailable for diary write",
             meta: {
                 reason: error instanceof Error ? error.message : String(error),
             },
@@ -248,13 +254,19 @@ async function buildEmbedding(text, embeddingProvider) {
         return [];
     }
 }
-function readMemoryFacts(memoryRoot = path.join((0, identity_1.getAgentRoot)(), "psyche", "memory")) {
-    return readExistingFacts(path.join(memoryRoot, "facts.jsonl"));
+function resolveDiaryRoot(explicitRoot) {
+    if (explicitRoot)
+        return explicitRoot;
+    const agentRoot = (0, identity_1.getAgentRoot)();
+    return path.join(agentRoot, "diary");
+}
+function readDiaryEntries(diaryRoot) {
+    return readExistingEntries(path.join(resolveDiaryRoot(diaryRoot), "facts.jsonl"));
 }
-async function saveMemoryFact(options) {
+async function saveDiaryEntry(options) {
     const text = options.text.trim();
-    const memoryRoot = options.memoryRoot ?? path.join((0, identity_1.getAgentRoot)(), "psyche", "memory");
-    const stores = ensureMemoryStorePaths(memoryRoot);
+    const diaryRoot = resolveDiaryRoot(options.diaryRoot);
+    const stores = ensureDiaryStorePaths(diaryRoot);
     const embedding = await buildEmbedding(text, options.embeddingProvider);
     const fact = {
         id: options.idFactory ? options.idFactory() : (0, crypto_1.randomUUID)(),
@@ -264,14 +276,14 @@ async function saveMemoryFact(options) {
         createdAt: (options.now ?? (() => new Date()))().toISOString(),
         embedding,
     };
-    return appendFactsWithDedup(stores, [fact]);
+    return appendEntriesWithDedup(stores, [fact], { semanticThreshold: SEMANTIC_DEDUP_THRESHOLD });
 }
 async function backfillEmbeddings(options) {
-    const memoryRoot = options?.memoryRoot ?? path.join((0, identity_1.getAgentRoot)(), "psyche", "memory");
-    const factsPath = path.join(memoryRoot, "facts.jsonl");
+    const diaryRoot = resolveDiaryRoot(options?.diaryRoot);
+    const factsPath = path.join(diaryRoot, "facts.jsonl");
     if (!fs.existsSync(factsPath))
         return { total: 0, backfilled: 0, failed: 0 };
-    const facts = readExistingFacts(factsPath);
+    const facts = readExistingEntries(factsPath);
     const needsEmbedding = facts.filter((f) => !Array.isArray(f.embedding) || f.embedding.length === 0);
     if (needsEmbedding.length === 0)
         return { total: facts.length, backfilled: 0, failed: 0 };
@@ -280,7 +292,7 @@ async function backfillEmbeddings(options) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
             component: "mind",
-            event: "mind.memory_backfill_skipped",
+            event: "mind.diary_backfill_skipped",
             message: "embedding provider unavailable for backfill",
             meta: { needsEmbedding: needsEmbedding.length },
         });
@@ -306,7 +318,7 @@ async function backfillEmbeddings(options) {
             (0, runtime_1.emitNervesEvent)({
                 level: "warn",
                 component: "mind",
-                event: "mind.memory_backfill_batch_error",
+                event: "mind.diary_backfill_batch_error",
                 message: "embedding backfill batch failed",
                 meta: {
                     batchStart: i,
@@ -319,9 +331,10 @@ async function backfillEmbeddings(options) {
     // Rewrite facts file with updated embeddings
     const lines = facts.map((f) => JSON.stringify(f)).join("\n") + "\n";
     fs.writeFileSync(factsPath, lines, "utf8");
+    (0, sync_1.trackSyncWrite)(factsPath);
     (0, runtime_1.emitNervesEvent)({
         component: "mind",
-        event: "mind.memory_backfill_complete",
+        event: "mind.diary_backfill_complete",
         message: "embedding backfill completed",
         meta: { total: facts.length, backfilled, failed },
     });
@@ -341,7 +354,7 @@ function uniqueFacts(facts) {
     }
     return unique;
 }
-async function searchMemoryFacts(query, facts, embeddingProvider) {
+async function searchDiaryEntries(query, facts, embeddingProvider) {
     const trimmed = query.trim();
     if (!trimmed)
         return [];
@@ -365,7 +378,7 @@ async function searchMemoryFacts(query, facts, embeddingProvider) {
             .filter((fact) => fact.embedding.length === queryEmbedding.length)
             .map((fact) => ({
             fact,
-            score: cosineSimilarity(queryEmbedding, fact.embedding),
+            score: (0, associative_recall_1.cosineSimilarity)(queryEmbedding, fact.embedding),
         }))
             .filter((entry) => entry.score > 0)
             .sort((left, right) => right.score - left.score)
@@ -377,8 +390,8 @@ async function searchMemoryFacts(query, facts, embeddingProvider) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
             component: "mind",
-            event: "mind.memory_embedding_unavailable",
-            message: "embedding provider unavailable for memory search",
+            event: "mind.diary_embedding_unavailable",
+            message: "embedding provider unavailable for diary search",
             meta: {
                 reason: error instanceof Error ? error.message : String(error),
             },

package/dist/mind/file-state.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileStateCache = exports.FileStateCache = void 0;
+exports.contentHash = contentHash;
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const runtime_1 = require("../nerves/runtime");
+/** Compute sha256 hex hash of content */
+function contentHash(content) {
+    return (0, crypto_1.createHash)("sha256").update(content).digest("hex");
+}
+/**
+ * Session-scoped LRU cache tracking file reads.
+ * Stores content hashes (not full content) to limit memory.
+ * Keyed by absolute file path.
+ *
+ * Also maintains a separate snapshot list for future rewind support.
+ * Snapshots are indexed by content hash and linked to conversation messages.
+ */
+class FileStateCache {
+    entries;
+    maxSize;
+    snapshots = [];
+    maxSnapshots = 100;
+    constructor(maxSize = 50) {
+        this.entries = new Map();
+        this.maxSize = maxSize;
+    }
+    /**
+     * Record a file read. Computes content hash and stores metadata.
+     */
+    record(filePath, content, mtime, offset, limit, messageId) {
+        // If key already exists, delete it so re-insertion moves it to end (most recent)
+        if (this.entries.has(filePath)) {
+            this.entries.delete(filePath);
+        }
+        const hash = contentHash(content);
+        const fullRead = offset === undefined && limit === undefined;
+        this.entries.set(filePath, {
+            hash,
+            mtime,
+            offset: fullRead ? undefined : offset,
+            limit: fullRead ? undefined : limit,
+            fullRead,
+            recordedAt: Date.now(),
+            messageId,
+        });
+        (0, runtime_1.emitNervesEvent)({
+            component: "mind",
+            event: "mind.file_state.record",
+            message: "recorded file state",
+            meta: { path: filePath, hash, fullRead },
+        });
+        // Evict LRU (first entry in Map iteration order) if over capacity
+        if (this.entries.size > this.maxSize) {
+            const firstKey = this.entries.keys().next().value;
+            this.entries.delete(firstKey);
+        }
+    }
+    /**
+     * Get the cached state for a file path. Also promotes it in LRU order.
+     */
+    get(filePath) {
+        const entry = this.entries.get(filePath);
+        if (entry === undefined)
+            return undefined;
+        // Promote to most-recently-used by re-inserting
+        this.entries.delete(filePath);
+        this.entries.set(filePath, entry);
+        (0, runtime_1.emitNervesEvent)({
+            component: "mind",
+            event: "mind.file_state.get",
+            message: "retrieved file state",
+            meta: { path: filePath, hash: entry.hash },
+        });
+        return entry;
+    }
+    /**
+     * Check if a file has been modified since the last recorded read.
+     * Uses mtime as primary signal, content hash as fallback for cloud sync / touch scenarios.
+     * Returns { stale: false } if the path is not in cache or the file cannot be stat'd.
+     */
+    isStale(filePath) {
+        const entry = this.entries.get(filePath);
+        if (entry === undefined)
+            return { stale: false };
+        let currentMtime;
+        try {
+            currentMtime = (0, fs_1.statSync)(filePath).mtimeMs;
+        }
+        catch {
+            // File doesn't exist or can't be stat'd -- no basis for staleness
+            return { stale: false };
+        }
+        // Fast path: mtime unchanged means not stale
+        if (currentMtime === entry.mtime)
+            return { stale: false };
+        // mtime differs -- check content hash as fallback (handles touch / cloud sync)
+        try {
+            const currentContent = (0, fs_1.readFileSync)(filePath, "utf-8");
+            const currentHash = contentHash(currentContent);
+            if (currentHash === entry.hash)
+                return { stale: false };
+            (0, runtime_1.emitNervesEvent)({
+                component: "mind",
+                event: "mind.file_state.stale_detected",
+                message: "file staleness detected",
+                meta: { path: filePath, previousHash: entry.hash, currentHash },
+            });
+            return { stale: true, reason: `file modified since last read (mtime and content differ)` };
+        }
+        catch {
+            // Can't read file -- treat as not stale (file may have been deleted)
+            return { stale: false };
+        }
+    }
+    /**
+     * Create a pre-edit snapshot of the current cache state for a file.
+     * Snapshots are stored separately from the LRU cache for future rewind support.
+     * Returns undefined if the path is not in cache.
+     */
+    snapshot(filePath) {
+        const entry = this.entries.get(filePath);
+        if (entry === undefined)
+            return undefined;
+        const snap = {
+            filePath,
+            hash: entry.hash,
+            mtime: entry.mtime,
+            messageId: entry.messageId,
+            createdAt: Date.now(),
+        };
+        this.snapshots.push(snap);
+        (0, runtime_1.emitNervesEvent)({
+            component: "mind",
+            event: "mind.file_state.snapshot_created",
+            message: "created file state snapshot",
+            meta: { path: filePath, hash: snap.hash },
+        });
+        // Evict oldest snapshots if over capacity
+        if (this.snapshots.length > this.maxSnapshots) {
+            this.snapshots = this.snapshots.slice(this.snapshots.length - this.maxSnapshots);
+        }
+        return snap;
+    }
+    /**
+     * Get all snapshots in creation order.
+     */
+    getSnapshots() {
+        return this.snapshots;
+    }
+    /**
+     * Look up a snapshot by content hash. Returns the first match.
+     */
+    lookupSnapshotByHash(hash) {
+        return this.snapshots.find(s => s.hash === hash);
+    }
+    /**
+     * Clear all snapshots.
+     */
+    clearSnapshots() {
+        this.snapshots = [];
+    }
+    /**
+     * Clear all cached entries (does not clear snapshots).
+     */
+    clear() {
+        (0, runtime_1.emitNervesEvent)({
+            component: "mind",
+            event: "mind.file_state.clear",
+            message: "cleared file state cache",
+            meta: { entryCount: this.entries.size },
+        });
+        this.entries.clear();
+    }
+}
+exports.FileStateCache = FileStateCache;
+/** Session-scoped singleton instance used by tool handlers */
+exports.fileStateCache = new FileStateCache();