@ouro.bot/cli 0.1.0-alpha.585 → 0.1.0-alpha.586

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_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.586",
+      "changes": [
+        "`mail_status`, `mail_recent`, `mail_search`, and `mail_index_refresh` now flag a 'mail substrate divergence' when the encrypted mailroom store reports zero visible messages but the on-disk search cache still holds documents from prior imports — the post-rotation / hosted→local-fallback / wiped-store state that previously rendered as a silent 'no mail' answer indistinguishable from a clean onboarding.",
+        "Mail absence answers from a divergent runtime now point at vault inspection (`mailroom.mode`, `mailroom.azureAccountUrl`, `mailroom.storePath`) and re-import recovery, so agents stop treating a broken substrate as evidence that the human inbox is empty.",
+        "The substrate-divergence snapshot counts cache `.json` entries via `readdir` and ignores subdirectories and non-json files, so the diagnostic stays cheap on bundles holding tens of thousands of cached documents."
+      ]
+    },
     {
       "version": "0.1.0-alpha.585",
       "changes": [

package/dist/mailroom/search-cache.js

@@ -38,6 +38,7 @@ exports.buildMailSearchCacheDocument = buildMailSearchCacheDocument;
 exports.upsertMailSearchCacheDocument = upsertMailSearchCacheDocument;
 exports.syncMailSearchCacheMetadata = syncMailSearchCacheMetadata;
 exports.searchMailSearchCache = searchMailSearchCache;
+exports.snapshotMailSearchCache = snapshotMailSearchCache;
 exports.readMailSearchCoverageRecord = readMailSearchCoverageRecord;
 exports.writeMailSearchCoverageRecord = writeMailSearchCoverageRecord;
 exports.resetMailSearchCacheForTests = resetMailSearchCacheForTests;
@@ -208,6 +209,17 @@ function searchMailSearchCache(filters, options) {
     }
     return typeof filters.limit === "number" ? ordered.slice(0, filters.limit) : ordered;
 }
+function snapshotMailSearchCache(agentId, options) {
+    const dir = cacheDir(agentId, options);
+    if (!fs.existsSync(dir))
+        return { totalDocuments: 0 };
+    let total = 0;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name.endsWith(".json"))
+            total += 1;
+    }
+    return { totalDocuments: total };
+}
 function readMailSearchCoverageRecord(key, options) {
     const document = readJsonDocument(coveragePath(key, options));
     if (!document || document.schemaVersion !== 1 || document.agentId !== key.agentId)

package/dist/repertoire/tools-mail.js

@@ -519,13 +519,42 @@ async function renderSourceGrantStatus(config, agentId) {
         ];
     }
 }
+/**
+ * When the encrypted mail store is empty but the on-disk search cache holds
+ * decrypted documents from prior imports, the agent has lost access to mail it
+ * previously had — typically because mail keys were rotated, the hosted blob
+ * pointer was dropped from the vault, or the encrypted store was wiped. The
+ * tools used to silently report "0 messages" in that state, which is the same
+ * answer they give for a fresh onboarding — so the agent could not tell a
+ * substrate failure from a clean slate. Surface the divergence loudly so the
+ * agent treats absence answers as suspect until the substrate is repaired.
+ */
+function describeMailSubstrateDivergence(input) {
+    if (input.visibleMessageCount > 0)
+        return null;
+    const snapshot = input.snapshot ?? (0, search_cache_1.snapshotMailSearchCache)(input.agentId);
+    if (snapshot.totalDocuments === 0)
+        return null;
+    return [
+        `mail substrate divergence: encrypted ${input.storeKind} store at ${input.storeLabel} has 0 visible messages, but the on-disk search cache for ${input.agentId} holds ${snapshot.totalDocuments} document(s).`,
+        "interpretation: this is not a fresh onboarding — prior imports populated the cache, then the encrypted store became unreachable (common causes: mail key rotation, hosted-store pointer dropped from vault during repair, encrypted store wiped). Mail absence answers from this runtime are not authoritative until the substrate is repaired.",
+        `agent next move: inspect runtime credentials (mailroom.mode, mailroom.azureAccountUrl, mailroom.storePath) — if the agent was previously hosted, the vault is missing the hosted pointer; coordinate with the human to restore it. If local mode is correct, re-import via 'ouro mail import-mbox --agent ${input.agentId} --owner-email <human-email> --source <source> --discover' so the encrypted store catches up to the cache.`,
+    ].join("\n");
+}
 async function renderEmptyMailResult(input) {
     const anyVisible = await input.store.listMessages({ agentId: input.agentId, limit: 1 });
     if (anyVisible.length === 0) {
         const sourceGrantStatus = await renderSourceGrantStatus(input.config, input.agentId);
+        const divergence = describeMailSubstrateDivergence({
+            agentId: input.agentId,
+            storeKind: input.storeKind,
+            storeLabel: input.storeLabel,
+            visibleMessageCount: 0,
+        });
         return [
             "No visible mail yet.",
             `mail onboarding status: Mailroom is provisioned for ${input.config.mailboxAddress}, but this agent's encrypted store has 0 messages.`,
+            ...(divergence ? [divergence] : []),
             ...sourceGrantStatus,
             "interpretation: this is not evidence that the human's HEY inbox is empty; Agent Mail has not yet received or imported mail visible to this agent.",
             `agent next move: guide setup from docs/agent-mail-setup.md. If HEY mail is needed, ensure the delegated hey alias exists, first try ouro mail import-mbox --agent ${input.agentId} --owner-email <human-email> --source hey --discover so Ouro can find a browser-downloaded export in .playwright-mcp or Downloads. Only ask the human for a file path if discovery cannot find a unique MBOX, then run ouro mail import-mbox --agent ${input.agentId} --owner-email <human-email> --source hey --file <mbox-path>. Verify with mail_recent/mail_search/Ouro Mailbox.`,
@@ -932,8 +961,8 @@ async function searchSuccessfulImportArchives(input) {
     }
     return matches.sort((left, right) => right.receivedAt.localeCompare(left.receivedAt));
 }
-async function renderMailStatus(agentId, config, storeLabel) {
-    const sourceGrantStatus = await renderSourceGrantStatus(config, agentId);
+async function renderMailStatus(input) {
+    const sourceGrantStatus = await renderSourceGrantStatus(input.config, input.agentId);
     const delegatedLines = sourceGrantStatus
         .flatMap((line) => line.startsWith("delegated source aliases: ")
         ? line
@@ -949,16 +978,24 @@ async function renderMailStatus(agentId, config, storeLabel) {
                 : `- delegated: ${grant}`;
         })
         : [`- ${line}`]);
+    const visible = await input.store.listMessages({ agentId: input.agentId, limit: 1 });
+    const divergence = describeMailSubstrateDivergence({
+        agentId: input.agentId,
+        storeKind: input.storeKind,
+        storeLabel: input.storeLabel,
+        visibleMessageCount: visible.length,
+    });
     return [
-        `mailbox: ${config.mailboxAddress}`,
-        `store: ${storeLabel}`,
+        `mailbox: ${input.config.mailboxAddress}`,
+        `store: ${input.storeLabel}`,
+        ...(divergence ? [divergence] : []),
         "lane map:",
-        `- native: ${config.mailboxAddress}`,
+        `- native: ${input.config.mailboxAddress}`,
         ...delegatedLines,
         "recent archives:",
-        ...renderRecentArchiveStatus(agentId),
+        ...renderRecentArchiveStatus(input.agentId),
         "recent imports:",
-        ...renderRecentImportOperations(agentId),
+        ...renderRecentImportOperations(input.agentId),
     ].join("\n");
 }
 exports.mailToolDefinitions = [
@@ -985,7 +1022,13 @@ exports.mailToolDefinitions = [
                 tool: "mail_status",
                 reason: "mail operating model overview",
             });
-            return renderMailStatus(resolved.agentName, resolved.config, resolved.storeLabel);
+            return renderMailStatus({
+                agentId: resolved.agentName,
+                config: resolved.config,
+                store: resolved.store,
+                storeKind: resolved.storeKind,
+                storeLabel: resolved.storeLabel,
+            });
         },
         summaryKeys: [],
     },
@@ -1039,6 +1082,8 @@ exports.mailToolDefinitions = [
                     agentId: resolved.agentName,
                     config: resolved.config,
                     store: resolved.store,
+                    storeKind: resolved.storeKind,
+                    storeLabel: resolved.storeLabel,
                     ...(scope ? { scope } : {}),
                     ...(args.source ? { source: args.source } : {}),
                 });
@@ -1394,6 +1439,8 @@ exports.mailToolDefinitions = [
                     agentId: resolved.agentName,
                     config: resolved.config,
                     store: resolved.store,
+                    storeKind: resolved.storeKind,
+                    storeLabel: resolved.storeLabel,
                     ...(scope ? { scope } : {}),
                     ...(args.source ? { source: args.source } : {}),
                 }), {
@@ -1485,6 +1532,12 @@ exports.mailToolDefinitions = [
                     reason: args.reason || "refresh mail search index",
                 });
                 const { coverage } = refreshed;
+                const divergence = describeMailSubstrateDivergence({
+                    agentId: resolved.agentName,
+                    storeKind: resolved.storeKind,
+                    storeLabel: resolved.storeLabel,
+                    visibleMessageCount: coverage.visibleMessageCount,
+                });
                 return [
                     "mail search index refreshed.",
                     `scope: ${scope ?? "all"}${args.source ? `; source: ${args.source}` : ""}${placement ? `; placement: ${placement}` : ""}`,
@@ -1496,6 +1549,7 @@ exports.mailToolDefinitions = [
                     `indexed at: ${coverage.indexedAt}`,
                     ...(coverage.oldestReceivedAt ? [`oldest: ${coverage.oldestReceivedAt}`] : []),
                     ...(coverage.newestReceivedAt ? [`newest: ${coverage.newestReceivedAt}`] : []),
+                    ...(divergence ? [divergence] : []),
                 ].join("\n");
             }
             catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.585",
+  "version": "0.1.0-alpha.586",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",