@ouro.bot/cli 0.1.0-alpha.534 → 0.1.0-alpha.536

package/changelog.json

@@ -1,6 +1,21 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.536",
+      "changes": [
+        "Delegated hosted mail search now tracks durable coverage records and refuses to treat stale cache misses as absence proof, with `mail_index_refresh` repairing projection-incomplete cache entries before coverage is considered current.",
+        "Mail ingestion, search caching, and body rendering now preserve searchable text from HTML-only messages, preventing travel facts from disappearing when an email lacks a plain-text body.",
+        "MCP send-message and daemon socket commands now fail with bounded timeout errors instead of hanging forever, and trip ledgers can be rendered as chronological calendars with evidence-backed `trip_calendar` output."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.535",
+      "changes": [
+        "Daemon orphan cleanup now recognizes managed mail sense workers, so stale `senses/mail-entry.js --agent <name>` processes from old runtimes are terminated on production daemon startup instead of lingering across restarts.",
+        "Adds regression coverage for the full daemon-managed entrypoint set used by orphan cleanup, including inner-dialog, daemon, BlueBubbles, Teams, and mail workers."
+      ]
+    },
     {
       "version": "0.1.0-alpha.534",
       "changes": [

package/dist/heart/daemon/daemon.js

@@ -105,6 +105,7 @@ function parseOrphanPidsFromPs(psOutput, selfPid) {
         if (!line.includes("agent-entry.js")
             && !line.includes("daemon-entry.js")
             && !line.includes("bluebubbles/entry.js")
+            && !line.includes("mail-entry.js")
             && !line.includes("teams-entry.js"))
             continue;
         // Parse `<pid> <ppid> <command...>`. ps pads these with leading spaces.

package/dist/heart/daemon/socket-client.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_DAEMON_SOCKET_PATH = void 0;
+exports.DEFAULT_DAEMON_COMMAND_TIMEOUT_MS = exports.DEFAULT_DAEMON_SOCKET_PATH = void 0;
 exports.__bypassVitestGuardForTests = __bypassVitestGuardForTests;
 exports.sendDaemonCommand = sendDaemonCommand;
 exports.checkDaemonSocketAlive = checkDaemonSocketAlive;
@@ -42,6 +42,7 @@ const fs = __importStar(require("fs"));
 const net = __importStar(require("net"));
 const runtime_1 = require("../../nerves/runtime");
 exports.DEFAULT_DAEMON_SOCKET_PATH = "/tmp/ouroboros-daemon.sock";
+exports.DEFAULT_DAEMON_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
 /**
  * Defense-in-depth: detect if we're running under vitest. Tests that forget
  * to `vi.mock("../../heart/daemon/socket-client")` would otherwise leak real
@@ -106,7 +107,7 @@ function shouldSuppressSocketCall(socketPath) {
         return true;
     return globalThis[BYPASS_KEY] !== true;
 }
-function sendDaemonCommand(socketPath, command) {
+function sendDaemonCommand(socketPath, command, options = {}) {
     if (shouldSuppressSocketCall(socketPath)) {
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
@@ -126,6 +127,41 @@ function sendDaemonCommand(socketPath, command) {
     return new Promise((resolve, reject) => {
         const client = net.createConnection(socketPath);
         let raw = "";
+        let settled = false;
+        const timeoutMs = options.timeoutMs ?? exports.DEFAULT_DAEMON_COMMAND_TIMEOUT_MS;
+        const resolveOnce = (response) => {
+            /* v8 ignore next -- duplicate settlement guard; callers also guard event handlers before reaching this helper @preserve */
+            if (settled)
+                return;
+            settled = true;
+            resolve(response);
+        };
+        const rejectOnce = (error) => {
+            /* v8 ignore next -- duplicate timeout/error races should not re-reject the command promise @preserve */
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        };
+        if ("setTimeout" in client && typeof client.setTimeout === "function") {
+            client.setTimeout(timeoutMs, () => {
+                const error = new Error(`Daemon command ${command.kind} timed out after ${timeoutMs}ms waiting for a response.`);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "daemon",
+                    event: "daemon.socket_command_timeout",
+                    message: "daemon socket command timed out",
+                    meta: {
+                        socketPath,
+                        kind: command.kind,
+                        timeoutMs,
+                        error: error.message,
+                    },
+                });
+                client.destroy();
+                rejectOnce(error);
+            });
+        }
         client.on("connect", () => {
             // Write the command + newline delimiter. DO NOT call client.end()
             // afterwards — the server closes the connection once it has written
@@ -149,6 +185,9 @@ function sendDaemonCommand(socketPath, command) {
             raw += chunk.toString("utf-8");
         });
         client.on("error", (error) => {
+            /* v8 ignore next -- duplicate post-settlement socket errors are ignored defensively @preserve */
+            if (settled)
+                return;
             (0, runtime_1.emitNervesEvent)({
                 level: "error",
                 component: "daemon",
@@ -160,9 +199,12 @@ function sendDaemonCommand(socketPath, command) {
                     error: error.message,
                 },
             });
-            reject(error);
+            rejectOnce(error);
         });
         client.on("end", () => {
+            /* v8 ignore next -- duplicate post-settlement socket end events are ignored defensively @preserve */
+            if (settled)
+                return;
             const trimmed = raw.trim();
             if (trimmed.length === 0 && command.kind === "daemon.stop") {
                 (0, runtime_1.emitNervesEvent)({
@@ -171,7 +213,7 @@ function sendDaemonCommand(socketPath, command) {
                     message: "daemon socket command completed",
                     meta: { socketPath, kind: command.kind, ok: true },
                 });
-                resolve({ ok: true, message: "daemon stopped" });
+                resolveOnce({ ok: true, message: "daemon stopped" });
                 return;
             }
             if (trimmed.length === 0) {
@@ -187,7 +229,7 @@ function sendDaemonCommand(socketPath, command) {
                         error: error.message,
                     },
                 });
-                reject(error);
+                rejectOnce(error);
                 return;
             }
             try {
@@ -202,7 +244,7 @@ function sendDaemonCommand(socketPath, command) {
                         ok: parsed.ok,
                     },
                 });
-                resolve(parsed);
+                resolveOnce(parsed);
             }
             catch (error) {
                 (0, runtime_1.emitNervesEvent)({
@@ -216,7 +258,7 @@ function sendDaemonCommand(socketPath, command) {
                         error: error instanceof Error ? error.message : String(error),
                     },
                 });
-                reject(error);
+                rejectOnce(error);
             }
         });
     });

package/dist/heart/mcp/mcp-server.js

@@ -33,8 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports._senseTurnRetryDelays = exports.SENSE_TURN_RETRY_DELAYS_MS = exports.SENSE_TURN_MAX_RETRIES = void 0;
+exports._senseTurnCommandTimeoutMs = exports._senseTurnRetryDelays = exports.SENSE_TURN_COMMAND_TIMEOUT_MS = exports.SENSE_TURN_RETRY_DELAYS_MS = exports.SENSE_TURN_MAX_RETRIES = void 0;
 exports._setSenseTurnRetryDelays = _setSenseTurnRetryDelays;
+exports._setSenseTurnCommandTimeoutMs = _setSenseTurnCommandTimeoutMs;
 exports.createMcpServer = createMcpServer;
 exports.getToolSchemas = getToolSchemas;
 const socket_client_1 = require("../daemon/socket-client");
@@ -44,9 +45,38 @@ const session_id_resolver_1 = require("../daemon/session-id-resolver");
 const pending_1 = require("../../mind/pending");
 exports.SENSE_TURN_MAX_RETRIES = 3;
 exports.SENSE_TURN_RETRY_DELAYS_MS = [1000, 2000, 4000];
+exports.SENSE_TURN_COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
 // Allow test override
 exports._senseTurnRetryDelays = exports.SENSE_TURN_RETRY_DELAYS_MS;
 function _setSenseTurnRetryDelays(delays) { exports._senseTurnRetryDelays = delays; }
+exports._senseTurnCommandTimeoutMs = exports.SENSE_TURN_COMMAND_TIMEOUT_MS;
+function _setSenseTurnCommandTimeoutMs(timeoutMs) { exports._senseTurnCommandTimeoutMs = timeoutMs; }
+async function withSenseTurnTimeout(promise, timeoutMs, command) {
+    let timer = null;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    const error = new Error(`MCP send_message to ${command.agent} timed out after ${timeoutMs}ms waiting for daemon response; command status is unknown.`);
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        component: "daemon",
+                        event: "daemon.mcp_sense_turn_timeout",
+                        message: "MCP senseTurn timed out waiting for daemon response",
+                        meta: { agent: command.agent, friendId: command.friendId, sessionKey: command.sessionKey, timeoutMs },
+                    });
+                    reject(error);
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        /* v8 ignore next -- Promise.race installs the timer synchronously; null is only a defensive cleanup guard @preserve */
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
  * Send a senseTurn command to the daemon with retry logic.
  * Retries on transient failures: empty response (daemon mid-restart),
@@ -57,7 +87,7 @@ async function sendSenseTurnWithRetry(socketPath, command) {
     /* v8 ignore start -- retry loop: functionally tested via mcp-send-message retry tests @preserve */
     for (let attempt = 0; attempt <= exports.SENSE_TURN_MAX_RETRIES; attempt++) {
         try {
-            const response = await (0, socket_client_1.sendDaemonCommand)(socketPath, command);
+            const response = await withSenseTurnTimeout((0, socket_client_1.sendDaemonCommand)(socketPath, command), exports._senseTurnCommandTimeoutMs, command);
             return response;
         }
         catch (error) {

package/dist/mailroom/blob-store.js

@@ -83,6 +83,17 @@ function isRetryableBlobDownloadError(error) {
         message.includes("etimedout") ||
         message.includes("socket closed");
 }
+function isBlobNotFoundError(error) {
+    const maybeStatus = typeof error === "object" && error !== null && "statusCode" in error
+        ? error.statusCode
+        : undefined;
+    if (maybeStatus === 404)
+        return true;
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return message.includes("blobnotfound") ||
+        message.includes("the specified blob does not exist") ||
+        message.includes("missing blob");
+}
 async function downloadJson(blob, timeoutMs) {
     if (!await blob.exists())
         return null;
@@ -102,6 +113,25 @@ async function downloadJson(blob, timeoutMs) {
     }
     throw normalizeBlobOperationError("download", blob, timeoutMs, lastError);
 }
+async function downloadIndexedJson(blob, timeoutMs) {
+    let lastError = null;
+    for (let attempt = 1; attempt <= DEFAULT_BLOB_DOWNLOAD_ATTEMPTS; attempt += 1) {
+        try {
+            const buffer = await withBlobOperationTimeout(timeoutMs, (abortSignal) => {
+                return blob.downloadToBuffer(undefined, undefined, { abortSignal });
+            });
+            return JSON.parse(buffer.toString("utf-8"));
+        }
+        catch (error) {
+            if (isBlobNotFoundError(error))
+                return null;
+            lastError = error;
+            if (attempt >= DEFAULT_BLOB_DOWNLOAD_ATTEMPTS || !isRetryableBlobDownloadError(error))
+                break;
+        }
+    }
+    throw normalizeBlobOperationError("download", blob, timeoutMs, lastError);
+}
 async function uploadJson(blob, value, timeoutMs) {
     try {
         await withBlobOperationTimeout(timeoutMs, (abortSignal) => {
@@ -275,20 +305,35 @@ class AzureBlobMailroomStore {
         await Promise.all(Array.from({ length: Math.min(MESSAGE_LIST_SCAN_CONCURRENCY, Math.max(messageBlobNames.length, 1)) }, async () => worker()));
         return applyOptionalLimit(matches.sort(compareNewestFirst), filters.limit);
     }
-    async listMessagesFromIndexes(filters) {
-        const messageIds = [];
+    async listMessageIndexRecords(filters) {
+        await this.ensureContainer();
+        const records = [];
         let sawIndex = false;
         for await (const item of this.container.listBlobsFlat({ prefix: messageIndexPrefix(filters.agentId) })) {
             sawIndex = true;
             const parsed = parseMessageIndexBlobName(item.name);
             if (!parsed || !messageMatchesFilters(parsed, filters))
                 continue;
-            messageIds.push(parsed.id);
-            if (typeof filters.limit === "number" && messageIds.length >= filters.limit)
+            records.push(parsed);
+            if (typeof filters.limit === "number" && records.length >= filters.limit)
                 break;
         }
         if (!sawIndex)
             return null;
+        const sorted = records.sort((left, right) => Date.parse(right.receivedAt) - Date.parse(left.receivedAt));
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_blob_store_message_indexes_listed",
+            message: "azure blob mailroom store listed message indexes",
+            meta: { agentId: filters.agentId, count: sorted.length },
+        });
+        return applyOptionalLimit(sorted, filters.limit);
+    }
+    async listMessagesFromIndexes(filters) {
+        const records = await this.listMessageIndexRecords(filters);
+        if (records === null)
+            return null;
+        const messageIds = records.map((record) => record.id);
         const messages = (await mapWithConcurrency(messageIds, this.messageFetchConcurrency, async (id) => {
             return downloadJson(this.messageBlob(id), this.blobOperationTimeoutMs);
         }))
@@ -404,6 +449,17 @@ class AzureBlobMailroomStore {
         });
         return message;
     }
+    async getIndexedMessageById(id) {
+        await this.ensureContainer();
+        const message = await downloadIndexedJson(this.messageBlob(id), this.blobOperationTimeoutMs);
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.mail_blob_store_indexed_message_read",
+            message: "azure blob mailroom store read message from known index",
+            meta: { id, found: message !== null },
+        });
+        return message;
+    }
     async listMessages(filters) {
         await this.ensureContainer();
         let filtered = await this.listMessagesFromIndexes(filters);

package/dist/mailroom/core.js

@@ -46,6 +46,8 @@ exports.encryptJsonForMailKey = encryptJsonForMailKey;
 exports.decryptMailJson = decryptMailJson;
 exports.resolveMailAddress = resolveMailAddress;
 exports.describeMailProvenance = describeMailProvenance;
+exports.htmlMailBodyToText = htmlMailBodyToText;
+exports.privateMailEnvelopeReadableText = privateMailEnvelopeReadableText;
 exports.buildStoredMailMessage = buildStoredMailMessage;
 exports.decryptStoredMailMessage = decryptStoredMailMessage;
 exports.provisionMailboxRegistry = provisionMailboxRegistry;
@@ -396,10 +398,56 @@ function candidateSender(input) {
 function normalizedIngestProvenance(input) {
     return input ?? { schemaVersion: 1, kind: "smtp" };
 }
+function decodeHtmlEntity(entity) {
+    const named = {
+        amp: "&",
+        apos: "'",
+        gt: ">",
+        lt: "<",
+        nbsp: " ",
+        quot: "\"",
+    };
+    const lowered = entity.toLowerCase();
+    if (named[lowered] !== undefined)
+        return named[lowered];
+    if (lowered.startsWith("#x")) {
+        const parsed = Number.parseInt(lowered.slice(2), 16);
+        return Number.isFinite(parsed) && parsed >= 0 && parsed <= 0x10ffff ? String.fromCodePoint(parsed) : `&${entity};`;
+    }
+    if (lowered.startsWith("#")) {
+        const parsed = Number.parseInt(lowered.slice(1), 10);
+        return Number.isFinite(parsed) && parsed >= 0 && parsed <= 0x10ffff ? String.fromCodePoint(parsed) : `&${entity};`;
+    }
+    return `&${entity};`;
+}
+function htmlMailBodyToText(html) {
+    return html
+        .replace(/<\s*(script|style|head|title|noscript)\b[^>]*>[\s\S]*?<\s*\/\s*\1\s*>/gi, " ")
+        .replace(/<\s*br\s*\/?\s*>/gi, "\n")
+        .replace(/<\s*\/?\s*(address|article|aside|blockquote|body|caption|div|figcaption|figure|footer|h[1-6]|header|hr|li|main|nav|ol|p|pre|section|table|tbody|td|tfoot|th|thead|tr|ul)\b[^>]*>/gi, "\n")
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&([a-zA-Z][a-zA-Z0-9]+|#[0-9]+|#x[0-9a-fA-F]+);/g, (_match, entity) => decodeHtmlEntity(entity))
+        .replace(/\r\n?/g, "\n")
+        .replace(/[ \t\f\v]+/g, " ")
+        .replace(/\n[ \t]+/g, "\n")
+        .replace(/[ \t]+\n/g, "\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+function privateMailEnvelopeReadableText(privateEnvelope) {
+    if (privateEnvelope.text.trim().length > 0)
+        return privateEnvelope.text;
+    if (!privateEnvelope.html || privateEnvelope.html.trim().length === 0)
+        return "";
+    return htmlMailBodyToText(privateEnvelope.html);
+}
 async function buildStoredMailMessage(input) {
     const parsed = await (0, mailparser_1.simpleParser)(input.rawMime);
     const id = messageStorageId(input.envelope, input.rawMime);
-    const text = parsed.text ?? "";
+    const html = typeof parsed.html === "string" ? parsed.html : undefined;
+    const parsedText = parsed.text ?? "";
+    /* v8 ignore next -- mailparser body-shape ternary permutations are covered by plain-text, HTML-only, and empty-MIME tests; this line is a projection adapter, not policy. @preserve */
+    const text = parsedText.trim().length > 0 ? parsedText : html ? htmlMailBodyToText(html) : "";
     const inReplyTo = typeof parsed.inReplyTo === "string" && parsed.inReplyTo.trim().length > 0
         ? parsed.inReplyTo.trim()
         : undefined;
@@ -422,7 +470,7 @@ async function buildStoredMailMessage(input) {
         subject: parsed.subject ?? "",
         date: parsed.date?.toISOString(),
         text,
-        html: typeof parsed.html === "string" ? parsed.html : undefined,
+        html,
         snippet: snippet(text || parsed.subject || "(no text body)"),
         attachments: parsed.attachments.map((attachment) => ({
             filename: attachment.filename ?? "(unnamed attachment)",

package/dist/mailroom/mbox-import.js

@@ -372,8 +372,9 @@ async function cacheMatchingMailSearchDocumentsFromMboxFile(input) {
             continue;
         (0, search_cache_1.upsertMailSearchCacheDocument)(message, privateEnvelope);
         matches.push(document);
-        if (matches.length >= input.limit)
-            break;
+        matches.sort((left, right) => (0, search_relevance_1.compareByRelevanceThenRecency)({ document: left, relevance: (0, search_relevance_1.scoreMailSearchDocument)(left, queryTerms) }, { document: right, relevance: (0, search_relevance_1.scoreMailSearchDocument)(right, queryTerms) }));
+        if (matches.length > input.limit)
+            matches.length = input.limit;
     }
     return matches
         .map((document) => ({ document, relevance: (0, search_relevance_1.scoreMailSearchDocument)(document, queryTerms) }))

package/dist/mailroom/reader.js

@@ -220,7 +220,9 @@ function resolveMailroomReader(agentName = (0, identity_2.getAgentName)()) {
 }
 async function resolveMailroomReaderWithRefresh(agentName = (0, identity_2.getAgentName)()) {
     const resolved = resolveMailroomReader(agentName);
-    if (resolved.ok || resolved.reason !== "auth-required" || !resolved.error.includes(" is unavailable")) {
+    if (resolved.ok
+        || resolved.reason !== "auth-required"
+        || (!resolved.error.includes(" is unavailable") && !resolved.error.includes(" is missing"))) {
         return resolved;
     }
     await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agentName, { preserveCachedOnFailure: true }).catch(() => undefined);

package/dist/mailroom/search-cache.js

@@ -33,17 +33,22 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAIL_SEARCH_TEXT_PROJECTION_VERSION = void 0;
 exports.buildMailSearchCacheDocument = buildMailSearchCacheDocument;
 exports.upsertMailSearchCacheDocument = upsertMailSearchCacheDocument;
 exports.syncMailSearchCacheMetadata = syncMailSearchCacheMetadata;
 exports.searchMailSearchCache = searchMailSearchCache;
+exports.readMailSearchCoverageRecord = readMailSearchCoverageRecord;
+exports.writeMailSearchCoverageRecord = writeMailSearchCoverageRecord;
 exports.resetMailSearchCacheForTests = resetMailSearchCacheForTests;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const identity_1 = require("../heart/identity");
 const runtime_1 = require("../nerves/runtime");
+const core_1 = require("./core");
 const search_relevance_1 = require("./search-relevance");
 const SEARCH_TEXT_EXCERPT_LIMIT = 16_384;
+exports.MAIL_SEARCH_TEXT_PROJECTION_VERSION = 2;
 const cacheStates = new Map();
 function cacheDir(agentId) {
     return path.join((0, identity_1.getAgentRoot)(agentId), "state", "mail-search");
@@ -51,11 +56,29 @@ function cacheDir(agentId) {
 function cachePath(agentId, messageId) {
     return path.join(cacheDir(agentId), `${messageId}.json`);
 }
+function coverageDir(agentId) {
+    return path.join(cacheDir(agentId), "coverage");
+}
+function normalizedCoverageKey(key) {
+    return {
+        agentId: key.agentId,
+        storeKind: key.storeKind,
+        ...(key.placement ? { placement: key.placement } : {}),
+        ...(key.compartmentKind ? { compartmentKind: key.compartmentKind } : {}),
+        ...(key.source ? { source: key.source.toLowerCase() } : {}),
+    };
+}
+function coveragePath(key) {
+    const normalized = normalizedCoverageKey(key);
+    const encoded = Buffer.from(JSON.stringify(normalized)).toString("base64url");
+    return path.join(coverageDir(normalized.agentId), `${encoded}.json`);
+}
 function normalizeSearchText(privateEnvelope) {
+    const readableText = (0, core_1.privateMailEnvelopeReadableText)(privateEnvelope);
     return [
         privateEnvelope.subject,
         privateEnvelope.snippet,
-        privateEnvelope.text.slice(0, SEARCH_TEXT_EXCERPT_LIMIT),
+        readableText.slice(0, SEARCH_TEXT_EXCERPT_LIMIT),
         privateEnvelope.from.join(" "),
     ].join("\n").toLowerCase();
 }
@@ -95,6 +118,7 @@ function loadCache(agentId) {
     return state.docs;
 }
 function buildMailSearchCacheDocument(message, privateEnvelope) {
+    const readableText = (0, core_1.privateMailEnvelopeReadableText)(privateEnvelope);
     return {
         schemaVersion: 1,
         messageId: message.id,
@@ -107,9 +131,10 @@ function buildMailSearchCacheDocument(message, privateEnvelope) {
         from: [...privateEnvelope.from],
         subject: privateEnvelope.subject,
         snippet: privateEnvelope.snippet,
-        textExcerpt: privateEnvelope.text.slice(0, SEARCH_TEXT_EXCERPT_LIMIT),
+        textExcerpt: readableText.slice(0, SEARCH_TEXT_EXCERPT_LIMIT),
         untrustedContentWarning: privateEnvelope.untrustedContentWarning,
         searchText: normalizeSearchText(privateEnvelope),
+        textProjectionVersion: exports.MAIL_SEARCH_TEXT_PROJECTION_VERSION,
         attachmentCount: privateEnvelope.attachments.length,
     };
 }
@@ -118,8 +143,9 @@ function upsertMailSearchCacheDocument(message, privateEnvelope) {
     const dir = cacheDir(message.agentId);
     fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(cachePath(message.agentId, message.id), `${JSON.stringify(document)}\n`, "utf-8");
-    const docs = loadCache(message.agentId);
-    docs.set(document.messageId, document);
+    const state = cacheState(message.agentId);
+    if (state.loaded)
+        state.docs.set(document.messageId, document);
     (0, runtime_1.emitNervesEvent)({
         component: "senses",
         event: "senses.mail_search_cache_upserted",
@@ -146,8 +172,9 @@ function syncMailSearchCacheMetadata(message) {
         ...(message.source ? { source: message.source } : {}),
     };
     fs.writeFileSync(cachePath(message.agentId, message.id), `${JSON.stringify(updated)}\n`, "utf-8");
-    const docs = loadCache(message.agentId);
-    docs.set(updated.messageId, updated);
+    const state = cacheState(message.agentId);
+    if (state.loaded)
+        state.docs.set(updated.messageId, updated);
 }
 function sourceMatches(source, filter) {
     if (!filter)
@@ -177,6 +204,49 @@ function searchMailSearchCache(filters) {
     }
     return typeof filters.limit === "number" ? ordered.slice(0, filters.limit) : ordered;
 }
+function readMailSearchCoverageRecord(key) {
+    const document = readJsonDocument(coveragePath(key));
+    if (!document || document.schemaVersion !== 1 || document.agentId !== key.agentId)
+        return null;
+    const normalized = normalizedCoverageKey(key);
+    const stored = normalizedCoverageKey(document);
+    if (JSON.stringify(stored) !== JSON.stringify(normalized))
+        return null;
+    return document;
+}
+function writeMailSearchCoverageRecord(record) {
+    const normalized = normalizedCoverageKey(record);
+    const document = {
+        schemaVersion: 1,
+        ...normalized,
+        indexedAt: record.indexedAt,
+        visibleMessageCount: record.visibleMessageCount,
+        cachedMessageCount: record.cachedMessageCount,
+        decryptableMessageCount: record.decryptableMessageCount,
+        skippedMessageCount: record.skippedMessageCount,
+        ...(record.messageIndexFingerprint ? { messageIndexFingerprint: record.messageIndexFingerprint } : {}),
+        textProjectionVersion: record.textProjectionVersion,
+        ...(record.oldestReceivedAt ? { oldestReceivedAt: record.oldestReceivedAt } : {}),
+        ...(record.newestReceivedAt ? { newestReceivedAt: record.newestReceivedAt } : {}),
+    };
+    fs.mkdirSync(coverageDir(document.agentId), { recursive: true });
+    fs.writeFileSync(coveragePath(document), `${JSON.stringify(document)}\n`, "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.mail_search_coverage_written",
+        message: "mail search coverage record written",
+        meta: {
+            agentId: document.agentId,
+            placement: document.placement ?? null,
+            compartmentKind: document.compartmentKind ?? null,
+            source: document.source ?? null,
+            storeKind: document.storeKind,
+            visibleMessageCount: document.visibleMessageCount,
+            decryptableMessageCount: document.decryptableMessageCount,
+        },
+    });
+    return document;
+}
 function resetMailSearchCacheForTests() {
     cacheStates.clear();
 }

package/dist/mind/prompt.js

@@ -472,6 +472,7 @@ function senseRuntimeGuidance(channel, preReadStatusLines) {
     lines.push("mail setup truth: Agent Mail uses Mailroom, not HEY OAuth/IMAP. For the full work substrate account, the agent-runnable command is `ouro account ensure --agent <agent> --owner-email <email> --source hey`; use `ouro connect mail --agent <agent> --owner-email <email> --source hey` for mail-only repair/provisioning, or `--no-delegated-source` for native-only mail. The detailed runbook is `docs/agent-mail-setup.md`.");
     lines.push("mail setup truth: HEY archive bootstrap still depends on HEY's browser-only export, but I should not offload path-discovery ceremony to the human. If browser MCP/Playwright downloaded the archive, I first try `ouro mail import-mbox --discover --owner-email <email> --source hey --agent <agent>` so Ouro can find the sandboxed copy in a repo/worktree `.playwright-mcp`, the home `.playwright-mcp`, or Downloads. If discovery cannot find a unique file, then I ask the human for the local MBOX path and run `ouro mail import-mbox --file <path> --owner-email <email> --source hey --agent <agent>` myself.");
     lines.push("mail setup truth: an empty Mailroom result is not proof the human's HEY inbox is empty. If `mail_recent`/`mail_search` reports no visible mail or no delegated mail, I treat onboarding/import/forwarding as unverified and guide the setup/import flow before reasoning from the absence of messages.");
+    lines.push("mail search proof rule: for delegated human mail, cache hits and recency slices are not corpus coverage. Before saying a booking, receipt, or work fact is missing, I use bounded `mail_search` with explicit scope/source terms and check its `search coverage:` line; if the live visible mailbox or imported archives were not searched, I repair search/import visibility instead of declaring a gap.");
     lines.push("mail validation answer shape: when a human asks for Agent Mail golden paths, answer with only these four named paths before claiming setup works:");
     lines.push("- golden path 1, HEY archive to work object: import the human-provided HEY MBOX and use delegated mail to update a real work object, such as travel plans.");
     lines.push("- golden path 2, native mail and Screener: send and receive agent-native mail, confirm unknown senders enter Screener, get family authorization for allow/discard, verify sender policy, and confirm discarded mail is recoverable.");

package/dist/repertoire/guardrails.js

@@ -301,7 +301,7 @@ const CREDENTIAL_TRUSTED_TOOLS = new Set(["credential_get", "credential_list"]);
 // advisory and geocode are public APIs but gated for consistency)
 // Flight search is also friend+ (read-only, no payment)
 const TRAVEL_TRUSTED_TOOLS = new Set(["weather_lookup", "travel_advisory", "geocode_search", "flight_search"]);
-const MAIL_FAMILY_TOOLS = new Set(["mail_screener", "mail_decide", "mail_access_log", "mail_send"]);
+const MAIL_FAMILY_TOOLS = new Set(["mail_screener", "mail_decide", "mail_access_log", "mail_send", "mail_index_refresh"]);
 const MAIL_DELEGATED_READ_TOOLS = new Set(["mail_recent", "mail_search"]);
 function mailTrustGuardrail(toolName, args, context) {
     if (MAIL_FAMILY_TOOLS.has(toolName)) {