ofw-mcp 2.6.7 → 2.7.1

package/dist/tools/messages.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { syncAll, fetchAttachmentMeta, fetchAttachmentMetaForMessage, getDraftsCacheStatus } from '../sync.js';
+import { buildFreshness } from './freshness.js';
 import { checkDraftFreshness, draftRevision, fetchServerDraft, staleDraftPayload, } from './draft-freshness.js';
+import { getFolderVerifiedAt } from '../sync.js';
+import { isHostRenderableImage, resolveDownloadMime } from './attachments.js';
 import { getAttachmentsDir, getDefaultInlineAttachments, getSyncMaxRequests, getWriteMode } from '../config.js';
 import { basename, join } from 'node:path';
 import { ApiRecipientSchema, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded, withReadState } from './_shared.js';
@@ -25,6 +28,8 @@ const SavedDraftDetailSchema = z.looseObject({
     date: DateSchema.optional(),
     replyToId: z.number().nullable().optional(),
     recipients: z.array(ApiRecipientSchema).optional(),
+    // Read to audit whether requested myFileIDs actually attached (Defect 3).
+    files: z.array(z.number()).optional(),
 });
 // ofw_get_message's uncached detail fetch — lenient: a mismatch warns to
 // stderr and the existing ?? fallbacks keep the tool serving.
@@ -43,6 +48,33 @@ const MessageDetailSchema = z.looseObject({
 });
 // Attachment-backfill detail fetch reads only `files`.
 const DetailFilesSchema = z.looseObject({ files: z.array(z.number()).optional() });
+// ofw_check_freshness' folder probe. `includeFolderCounts=true` returns a
+// per-folder count, but the field name varies across OFW payload versions —
+// accept the known spellings and degrade to a null serverCount rather than
+// guessing, since a wrong count would manufacture a false out-of-sync verdict.
+const FolderCountsSchema = z.looseObject({
+    systemFolders: z.array(z.looseObject({
+        id: z.string(),
+        folderType: z.string(),
+        totalCount: z.number().optional(),
+        messageCount: z.number().optional(),
+        count: z.number().optional(),
+    })).optional(),
+});
+const FOLDER_TYPE = {
+    inbox: 'INBOX',
+    sent: 'SENT_MESSAGES',
+    drafts: 'DRAFTS',
+};
+/**
+ * Cap on per-id probes in one ofw_check_freshness call.
+ *
+ * Each id costs one OFW request, and on the hosted Worker every request counts
+ * against the subrequest cap (see OFW_SYNC_MAX_REQUESTS). The check has to stay
+ * cheap enough that a caller reaches for it freely — that is the entire point
+ * of it existing — so it truncates loudly rather than turning into a sync.
+ */
+const MAX_FRESHNESS_IDS = 25;
 // Upload response — STRICT: fileId is the whole point of the call; caching
 // or returning an undefined/mistyped fileId produces an unusable attachment.
 const UploadedFileSchema = z.looseObject({
@@ -67,6 +99,32 @@ function listDataHintsAtFiles(listData) {
         return ld.files.length > 0;
     return false;
 }
+/**
+ * Freshness for a drafts read, plus the per-draft `serverConfirmed` flag.
+ *
+ * `serverConfirmed` answers the question that triggered this whole mechanism:
+ * "is this draft actually still sitting unsent on OFW?" It is true ONLY when a
+ * completed drafts walk verified the cache against OFW within the freshness
+ * window (getFreshnessTtlSeconds, default 300s) — NOT a claim about this exact
+ * instant, which no cache can make. Anything less — a deferred walk, an aged
+ * stamp, a cache that was never checked — is false, meaning the draft's
+ * existence and unsent status are remembered, not known. On a false, a caller
+ * must not state either as present-tense fact without calling
+ * ofw_check_freshness first.
+ */
+async function draftsFreshness(cache) {
+    const freshness = await buildFreshness(cache, { source: 'cache', folders: ['drafts'] });
+    // Reconcile the two signals so a single response can never contradict
+    // itself (the same rule withReadState applies to read flags). The drafts
+    // meta key says whether the last walk COMPLETED; freshness additionally
+    // knows whether that walk has since aged out or been overtaken by a sync
+    // that skipped drafts. Downgrade only — this can turn 'fresh' off, never on.
+    const completed = await getDraftsCacheStatus(cache);
+    const cacheStatus = completed === 'fresh' && freshness.staleness === 'fresh'
+        ? 'fresh'
+        : 'unverified';
+    return { freshness, serverConfirmed: cacheStatus === 'fresh', cacheStatus };
+}
 export function registerMessageTools(server, client, cacheProvider, attachmentIO) {
     // OFW_WRITE_MODE gate (see config.ts). Send lands on the court-visible
     // record, so it is 'all'-only; draft-level writes (save/delete drafts,
@@ -76,11 +134,12 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     const allowSend = writeMode === 'all';
     const allowDrafts = writeMode !== 'none';
     server.registerTool('ofw_list_message_folders', {
-        description: 'List OurFamilyWizard message folders (inbox, sent, etc.) and their unread counts. Returns folder IDs needed to call ofw_list_messages. Does NOT return message content.',
+        description: 'List OurFamilyWizard message folders (inbox, sent, etc.) and their unread counts. Fetched LIVE from OFW, so the counts are current. Returns folder IDs needed to call ofw_list_messages. Does NOT return message content.',
         annotations: { readOnlyHint: true },
     }, async () => {
         const data = await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true');
-        return jsonResponse(data);
+        const freshness = await buildFreshness(cacheProvider(), { source: 'live', folders: [] });
+        return jsonResponse({ folders: data, freshness });
     });
     server.registerTool('ofw_list_messages', {
         description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based but if you know what you want (a date range, a topic), prefer the filters over walking pages — the cache may have 1000+ messages. Call ofw_sync_messages first if the cache is empty or stale.',
@@ -105,9 +164,16 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         else if (folderArg === 'both')
             folder = undefined;
         else {
+            // Still carries freshness: `messages: []` with no age label is exactly
+            // the shape this mechanism exists to eliminate, even when the emptiness
+            // is caused by a bad argument rather than an empty cache.
             return jsonResponse({
                 messages: [],
-                note: 'folderId must be "inbox", "sent", or "both". Numeric OFW folder IDs are not supported by the cache.',
+                freshness: await buildFreshness(cacheProvider(), {
+                    source: 'cache',
+                    folders: ['inbox', 'sent'],
+                }),
+                note: 'folderId must be "inbox", "sent", or "both". Numeric OFW folder IDs are not supported by the cache. No lookup was performed — this empty result says nothing about what is in the cache.',
             });
         }
         const cache = cacheProvider();
@@ -118,7 +184,14 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         // from the record's own `viewedAt`/`fetchedBodyAt` and `listData` is forced
         // to agree — see withReadState.
         const messages = (await cache.listMessages({ ...filter, page, size })).map((m) => withReadState(m));
-        const payload = { messages, total, page, size };
+        // Served from the local cache, so the result must say how old it is and
+        // whether anything vouches for it — a caller cannot state current state
+        // from this payload without either re-reading or surfacing the caveat.
+        const freshness = await buildFreshness(cache, {
+            source: 'cache',
+            folders: folder === undefined ? ['inbox', 'sent'] : [folder],
+        });
+        const payload = { messages, total, page, size, freshness };
         if (total === 0) {
             payload.note = 'No messages match these filters. If you expected results, check ofw_sync_messages was run, or relax the filters.';
         }
@@ -144,6 +217,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         // up — see syncDrafts, which also evicts these stale rows.
         const draftRow = await cache.getDraft(id);
         if (draftRow !== null) {
+            const { freshness, serverConfirmed, cacheStatus } = await draftsFreshness(cache);
             return jsonResponse({
                 id: draftRow.id,
                 folder: 'drafts',
@@ -163,7 +237,12 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 // Concurrency token — pass as expectedRevision to ofw_save_draft /
                 // ofw_delete_draft to assert you are editing THIS version.
                 revision: draftRevision(draftRow),
-                cacheStatus: await getDraftsCacheStatus(cache),
+                cacheStatus,
+                // False = this draft's existence and unsent status are remembered from
+                // a cache, not confirmed on OFW. Call ofw_check_freshness before
+                // stating either as current fact.
+                serverConfirmed,
+                freshness,
             });
         }
         const cached = await cache.getMessage(id);
@@ -214,7 +293,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     // Backfill is best-effort. Fall through with whatever we have.
                 }
             }
-            return jsonResponse({ ...withReadState(row), attachments });
+            // Cache-served: the body is whatever the last sync stored. Even though
+            // this call may have re-hit detail for view status, the message content
+            // itself was not re-verified, so report the folder's cache freshness.
+            const freshness = await buildFreshness(cache, { source: 'cache', folders: [row.folder] });
+            return jsonResponse({ ...withReadState(row), attachments, freshness });
         }
         const detail = parseLenient(MessageDetailSchema, await client.request('GET', `/pub/v3/messages/${encodeURIComponent(args.messageId)}`), { label: 'ofw-mcp', context: 'GET /pub/v3/messages/{id} (ofw_get_message)' });
         // Derive the folder for a live-fetched message. A cached row (reached here
@@ -249,7 +332,9 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             await fetchAttachmentMetaForMessage(client, detail.id, detail.files, cache);
         }
         const attachments = await cache.listAttachmentsForMessage(detail.id);
-        return jsonResponse({ ...withReadState(row), attachments });
+        // Fetched live from OFW in this call — current by construction.
+        const freshness = await buildFreshness(cache, { source: 'live', folders: [folder] });
+        return jsonResponse({ ...withReadState(row), attachments, freshness });
     });
     if (allowSend)
         server.registerTool('ofw_send_message', {
@@ -414,8 +499,15 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             };
         }
         const verdict = checkDraftFreshness({ server, cached, expectedRevision });
-        if (verdict.verdict === 'FRESH')
-            return { ok: true, note: null };
+        if (verdict.verdict === 'FRESH') {
+            // A metadata-only "conflict" is the connector's own post-save replyToId
+            // normalization catching up — safe to proceed, but say so rather than
+            // pretending nothing moved.
+            const note = verdict.metadataOnly
+                ? `NOTE: draft ${draftId} was treated as current for this ${action}. Since you read it, OurFamilyWizard normalized connector-authored metadata (${verdict.changedFields.join(', ')}); the subject, body and recipients are unchanged, so this is not a conflict.`
+                : null;
+            return { ok: true, note };
+        }
         if (force) {
             // Loud, and the overwritten content rides along in the response so it is
             // recoverable from the tool result itself.
@@ -450,23 +542,34 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         const page = args.page ?? 1;
         const size = args.size ?? 50;
         const cache = cacheProvider();
-        const cacheStatus = await getDraftsCacheStatus(cache);
+        const { freshness, serverConfirmed, cacheStatus } = await draftsFreshness(cache);
         const rows = await cache.listDrafts({ page, size });
         // Every draft carries the concurrency token to echo back on a write, plus
-        // whether the last sync actually compared this cache against OFW.
-        const drafts = rows.map((d) => ({ ...d, revision: draftRevision(d), cacheStatus }));
+        // whether the last sync actually compared this cache against OFW and
+        // whether its presence-on-server is confirmed or merely remembered.
+        const drafts = rows.map((d) => ({
+            ...d,
+            revision: draftRevision(d),
+            cacheStatus,
+            serverConfirmed,
+            asOf: freshness.asOf,
+        }));
         if (drafts.length === 0) {
-            return jsonResponse({ drafts: [], note: 'Cache empty. Call ofw_sync_messages to populate.' });
+            return jsonResponse({
+                drafts: [],
+                freshness,
+                note: 'No drafts in the local cache. That is NOT proof there are no drafts on OurFamilyWizard — call ofw_sync_messages to populate, or ofw_check_freshness to confirm.',
+            });
         }
-        const payload = { drafts };
-        if (cacheStatus !== 'fresh') {
-            payload.note = 'cacheStatus "unverified": the last ofw_sync_messages did not finish checking the drafts folder against OurFamilyWizard, so these bodies may be behind the server (drafts edited in the OFW web app do not bump any timestamp). Run ofw_sync_messages again before relying on them. Writes are guarded regardless — ofw_save_draft and ofw_delete_draft re-check the server and refuse a stale overwrite.';
+        const payload = { drafts, freshness };
+        if (!serverConfirmed) {
+            payload.note = 'serverConfirmed:false — these drafts are remembered from the local cache, NOT confirmed to still exist unsent on OurFamilyWizard right now, and their bodies may be behind the server. Do not state that a draft "is still sitting unsent" on this basis; drafts edited or deleted in the OFW web app bump no timestamp, so the cache cannot detect it on its own. Call ofw_check_freshness (cheap, live) or ofw_sync_messages first. Writes are guarded regardless — ofw_save_draft and ofw_delete_draft re-check the server and refuse a stale overwrite.';
         }
         return jsonResponse(payload);
     });
     if (allowDrafts)
         server.registerTool('ofw_save_draft', {
-            description: 'Save a message as a draft in OurFamilyWizard. Recipients are optional. Pass messageId to replace an existing draft — note that under the hood this creates a NEW draft and deletes the old one (OFW\'s update-in-place endpoint silently no-ops while echoing the posted body, so we don\'t use it); the response.id will be the NEW id, not the messageId you passed, and the change is documented in a transparency NOTE in the response. If replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included in response). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After saving, the tool re-fetches the draft from OFW to populate the local cache from authoritative server state. SAFETY: because replacing DESTROYS the old draft rather than merging, passing messageId first re-reads that draft from OFW and REFUSES the write if it changed since you read it (drafts edited in the OFW web app do not bump any timestamp, so the local cache can be silently behind). The refusal returns the current server body under serverBody — merge your edit into it and retry with expectedRevision.',
+            description: 'Save a message as a draft in OurFamilyWizard. Recipients are optional. Pass messageId to replace an existing draft — note that under the hood this creates a NEW draft and deletes the old one (OFW\'s update-in-place endpoint silently no-ops while echoing the posted body, so we don\'t use it); the response.id will be the NEW id, not the messageId you passed, and the change is documented in a transparency NOTE in the response that also lists which fields (subject/body/recipients/replyToId/attachments) were carried over. If replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included in response). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After saving, the tool re-fetches the draft from OFW to populate the local cache from authoritative server state, and the returned `revision` reflects that authoritative state (so it will match on your next edit). FIELD PRESERVATION: the response echoes the effective threading (replyToId/inReplyTo) and, whenever OFW did not carry over a requested replyToId, recipient or attachment, a `warnings[]` entry naming what was dropped — never a silent null. SAFETY: because replacing DESTROYS the old draft rather than merging, passing messageId first re-reads that draft from OFW and REFUSES the write if its subject/body/recipients changed since you read it (drafts edited in the OFW web app do not bump any timestamp, so the local cache can be silently behind). A pure replyToId normalization by OFW is NOT treated as a conflict. The refusal returns the current server body under serverBody — merge your edit into it and retry with expectedRevision.',
             annotations: { readOnlyHint: false },
             inputSchema: {
                 subject: z.string().describe('Message subject'),
@@ -525,26 +628,63 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             let replaceNote = null;
             let verifyNote = null;
             let newRevision = null;
+            // Fields accepted on the write that the saved draft must carry — or their
+            // loss must be reported. Never a silent drop (Defect 3).
+            const warnings = [];
             if (newId !== null) {
                 verifyNote = verifyWriteLanded('draft', { subject: args.subject, body: args.body }, detail);
+                // Trust the re-fetched server detail as the source of truth for the stored
+                // replyToId — NOT `resolvedReplyTo` (what we intended to post). OFW
+                // normalizes/drops threading after a save, and masking that with our own
+                // intent (the old `detail.replyToId ?? resolvedReplyTo`) both returned a
+                // revision that was stale on arrival (Defect 1) and hid a dropped reply
+                // link (Defect 3). `?? null` keeps a genuinely-echoed value and reflects a
+                // null/absent one honestly.
+                const effectiveReplyTo = detail.replyToId ?? null;
+                const storedRecipients = mapRecipients(detail.recipients);
                 persisted = {
                     id: newId,
                     subject: detail.subject ?? args.subject,
                     body: detail.body ?? '',
-                    recipients: mapRecipients(detail.recipients),
-                    replyToId: detail.replyToId ?? resolvedReplyTo,
+                    recipients: storedRecipients,
+                    replyToId: effectiveReplyTo,
                     modifiedAt: detail.date?.dateTime ?? new Date().toISOString(),
                     listData: detail,
                 };
                 await cache.upsertDraft(persisted);
+                // The revision is now computed from the server-authoritative detail, so it
+                // is the value a subsequent read/verify will observe (Defect 1).
                 newRevision = draftRevision(persisted);
+                // Audit every field the caller supplied against what actually landed, so a
+                // silent normalization becomes a visible warning rather than a surprise.
+                if (resolvedReplyTo !== null && effectiveReplyTo !== resolvedReplyTo) {
+                    const rewrittenFrom = requestedReplyTo !== resolvedReplyTo ? ` (rewritten from ${requestedReplyTo})` : '';
+                    warnings.push(`replyToId was requested as ${resolvedReplyTo}${rewrittenFrom} but the saved draft came back with replyToId ${effectiveReplyTo === null ? 'null' : effectiveReplyTo} — OurFamilyWizard did not thread this draft (its inReplyTo/showContext will be empty). The subject and body were saved; only the reply linkage was dropped. If threading matters, verify on ourfamilywizard.com.`);
+                }
+                // Only warn on recipients/attachments when the detail actually reported
+                // them — an omitted array is "not echoed", not "dropped", and crying wolf
+                // there would desensitize the caller to the real drops.
+                if (args.recipientIds !== undefined && Array.isArray(detail.recipients)) {
+                    const requested = [...new Set(args.recipientIds)].sort((a, b) => a - b);
+                    const stored = [...new Set(storedRecipients.map((r) => r.userId))].sort((a, b) => a - b);
+                    if (requested.join(',') !== stored.join(',')) {
+                        warnings.push(`recipientIds were requested as [${requested.join(', ')}] but the saved draft has [${stored.join(', ')}]. Verify the recipients on ourfamilywizard.com.`);
+                    }
+                }
+                if (myFileIDs.length > 0 && Array.isArray(detail.files)) {
+                    const storedFiles = new Set(detail.files);
+                    const missing = myFileIDs.filter((id) => !storedFiles.has(id));
+                    if (missing.length > 0) {
+                        warnings.push(`Attachment fileId(s) ${missing.join(', ')} were requested in myFileIDs but are not attached to the saved draft. Re-upload or re-attach if needed.`);
+                    }
+                }
                 // Replace-path: caller passed messageId, so they want the old draft
                 // gone. Delete it after the new one is safely created+cached.
                 if (args.messageId !== undefined && args.messageId !== newId) {
                     try {
                         await deleteOFWMessages(client, [args.messageId]);
                         await cache.deleteDraft(args.messageId);
-                        replaceNote = `NOTE: ofw_save_draft replaced draft ${args.messageId} via create-then-delete. The new draft id is ${newId}; the old draft has been deleted. (OFW's update-in-place endpoint silently no-ops on subsequent updates, so we never use it. If you cached the old id anywhere, replace it with the new one.)`;
+                        replaceNote = `NOTE: ofw_save_draft replaced draft ${args.messageId} via create-then-delete. The new draft id is ${newId}; the old draft has been deleted. (OFW's update-in-place endpoint silently no-ops on subsequent updates, so we never use it. If you cached the old id anywhere, replace it with the new one.) Fields carried over to the new draft: subject, body, recipients (${persisted.recipients.length}), replyToId (${persisted.replyToId === null ? 'none' : persisted.replyToId}), attachments (${myFileIDs.length}).${warnings.length > 0 ? ' See warnings above for any field OurFamilyWizard did not carry over.' : ''}`;
                     }
                     catch (e) {
                         // Partial-failure safety: the new draft is already created and
@@ -554,11 +694,26 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     }
                 }
             }
+            // The draft was just re-fetched from OFW by postMessageAndRefetch, so this
+            // one row IS server-confirmed regardless of the drafts folder's overall
+            // cache freshness. `inReplyTo` echoes the effective threading alongside the
+            // volatile `id`, and `warnings` names any requested field that did not land.
             const responseObj = persisted !== null
-                ? { ...persisted, revision: newRevision, cacheStatus: 'fresh' }
+                ? {
+                    ...persisted,
+                    inReplyTo: persisted.replyToId,
+                    revision: newRevision,
+                    cacheStatus: 'fresh',
+                    serverConfirmed: true,
+                    ...(warnings.length > 0 ? { warnings } : {}),
+                }
                 : raw;
             const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Draft saved.';
-            const notes = [forceNote, rewriteNote, verifyNote, replaceNote].filter((n) => n !== null).join('\n\n');
+            const warnNote = warnings.length > 0
+                ? `WARNING: ${warnings.join('\n\n')}`
+                : null;
+            const notes = [forceNote, rewriteNote, verifyNote, warnNote, replaceNote]
+                .filter((n) => n !== null).join('\n\n');
             return textResponse(notes ? `${notes}\n\n${text}` : text);
         });
     if (allowDrafts)
@@ -596,9 +751,18 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
-        const sent = await cacheProvider().listMessages({ folder: 'sent', page, size });
+        const cache = cacheProvider();
+        const sent = await cache.listMessages({ folder: 'sent', page, size });
+        // "Nobody has read it yet" is a present-tense claim drawn entirely from
+        // cached view timestamps, which only move when a sync refreshes them —
+        // so it needs the same age label as any other cached read.
+        const freshness = await buildFreshness(cache, { source: 'cache', folders: ['sent'] });
         if (sent.length === 0) {
-            return jsonResponse({ note: 'Sent cache is empty. Call ofw_sync_messages to populate.' });
+            return jsonResponse({
+                unread: [],
+                freshness,
+                note: 'Sent cache is empty. Call ofw_sync_messages to populate. An empty cache is NOT evidence that no sent messages exist.',
+            });
         }
         const unread = [];
         for (const msg of sent) {
@@ -608,9 +772,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             }
         }
         if (unread.length === 0) {
-            return jsonResponse({ message: 'All scanned sent messages have been read.' });
+            return jsonResponse({
+                unread: [],
+                freshness,
+                message: 'All scanned sent messages had been read as of the timestamp in `freshness.asOf`. A recipient may have read a message since without the cache hearing about it.',
+            });
         }
-        return jsonResponse(unread);
+        return jsonResponse({ unread, freshness });
     });
     if (allowDrafts)
         server.registerTool('ofw_upload_attachment', {
@@ -657,18 +825,24 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             });
         });
     server.registerTool('ofw_download_attachment', {
-        description: 'Download an OFW message attachment by fileId. By default, bytes are saved to disk (~/Downloads/ofw-mcp/) and the response carries the absolute path, mime type, and size for the caller to read back. Pass inline:true to skip disk entirely and return the bytes as MCP content blocks — images come back as ImageContent (the model sees them directly); other files come back as an EmbeddedResource blob. Use inline for small files where you want the model to read content immediately and the host is sandboxed; use disk for large files or when you want a persistent local copy. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var (set to "true" to make inline the default). fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo. Re-downloading to the same path is a no-op (disk mode only).',
+        description: 'Download an OFW message attachment by fileId. By default, bytes are saved to disk (~/Downloads/ofw-mcp/) and the response carries the absolute path, mime type, and size for the caller to read back. Pass inline:true to skip disk entirely and return the bytes as MCP content blocks — host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent (the model sees them directly); every other file comes back as an EmbeddedResource blob carrying the bytes. Reported mime types are always normalized to a bare media type (no charset/name parameters). Use inline for small files where you want the model to read content immediately and the host is sandboxed; use disk for large files or when you want a persistent local copy. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var (set to "true" to make inline the default). On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (the response is marked forcedInline:true) rather than failing. fileId comes from attachments[].fileId on ofw_get_message. Override disk destination with OFW_ATTACHMENTS_DIR or saveTo. Re-downloading to the same path is a no-op (disk mode only).',
         annotations: { readOnlyHint: false },
         inputSchema: {
             fileId: z.number().describe('Attachment file id (from ofw_get_message → attachments[].fileId)'),
-            inline: z.boolean().describe('If true, return bytes inline as MCP content (image for image/*, embedded resource blob otherwise) and skip the disk write. If false, write to disk and return the path. If omitted, falls back to the OFW_INLINE_ATTACHMENTS env var (default: false = disk).').optional(),
-            saveTo: z.string().describe('Absolute path or directory to write to. If a directory, the OFW filename is used. Default: ~/Downloads/ofw-mcp/<fileId>-<filename>. Ignored when inline:true.').optional(),
+            inline: z.boolean().describe('If true, return bytes inline as MCP content (ImageContent for host-renderable images, embedded resource blob otherwise) and skip the disk write. If false, write to disk and return the path — except on a hosted deployment with no filesystem, where inline is forced (forcedInline:true) so the bytes are still returned. If omitted, falls back to the OFW_INLINE_ATTACHMENTS env var (default: false = disk).').optional(),
+            saveTo: z.string().describe('Absolute path or directory to write to. If a directory, the OFW filename is used. Default: ~/Downloads/ofw-mcp/<fileId>-<filename>. Ignored when inline is in effect.').optional(),
             force: z.boolean().describe('Re-download even if already on disk. Default false. Ignored when inline:true (inline always fetches fresh bytes, or reuses an on-disk copy if present).').optional(),
         },
     }, async (args) => {
         const fileId = args.fileId;
         const cache = cacheProvider();
-        const inline = args.inline ?? getDefaultInlineAttachments();
+        const requestedInline = args.inline ?? getDefaultInlineAttachments();
+        // When the deployment has no filesystem (hosted connector), inline is the
+        // ONLY path to the bytes — force it rather than erroring on a disk write.
+        // `forcedInline` records that we overrode an explicit `inline:false` so the
+        // response is honest about it instead of silently ignoring the argument.
+        const inline = requestedInline || !attachmentIO.supportsDisk;
+        const forcedInline = inline && !requestedInline;
         let cached = await cache.getAttachment(fileId);
         if (!cached) {
             // Not in cache. Fetch metadata and store under the messageId=0
@@ -682,7 +856,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         if (inline) {
             // Reuse on-disk bytes if we already have them; otherwise fetch fresh.
             let bytes = null;
-            let mimeType = cached.mimeType;
+            let headerMime = cached.mimeType;
             let fileName = cached.fileName;
             if (cached.downloadedPath) {
                 bytes = attachmentIO.readDownloaded(cached.downloadedPath);
@@ -690,14 +864,25 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             if (bytes === null) {
                 const response = await client.requestBinary('GET', `/pub/v1/myfiles/${fileId}/data`);
                 bytes = response.body;
-                mimeType = response.contentType ?? cached.mimeType;
+                headerMime = response.contentType ?? cached.mimeType;
                 fileName = response.suggestedFileName ?? cached.fileName;
             }
+            // Normalize to a bare media type: sniff the bytes first (OFW tacks a bogus
+            // charset onto binaries), then fall back to the stripped header, then the
+            // extension. A parameter suffix would make the host reject an image.
+            const mimeType = resolveDownloadMime(bytes, headerMime, fileName);
             const base64 = bytes.toString('base64');
-            const metaBlock = { type: 'text', text: JSON.stringify({
-                    fileId, fileName, mimeType, sizeBytes: bytes.length, mode: 'inline',
-                }, null, 2) };
-            if (mimeType.startsWith('image/')) {
+            const meta = {
+                fileId, fileName, mimeType, sizeBytes: bytes.length, mode: 'inline',
+            };
+            if (forcedInline)
+                meta.forcedInline = true;
+            const metaBlock = { type: 'text', text: JSON.stringify(meta, null, 2) };
+            // Only host-renderable image types go back as ImageContent (with the bare
+            // media type the renderer accepts); everything else — non-renderable
+            // images included — goes back as an EmbeddedResource so the caller always
+            // gets the bytes.
+            if (isHostRenderableImage(mimeType)) {
                 return { content: [metaBlock, { type: 'image', data: base64, mimeType }] };
             }
             return { content: [metaBlock, { type: 'resource', resource: {
@@ -723,38 +908,172 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         }
         if (!args.force && cached.downloadedPath === dest) {
             return jsonResponse({
-                fileId, path: dest, mimeType: cached.mimeType, sizeBytes: cached.sizeBytes,
-                fileName: cached.fileName, note: 'already downloaded',
+                // No bytes on hand for the no-op case: normalize the cached/extension
+                // MIME (empty buffer sniffs nothing) so a stored `image/png;charset=…`
+                // still reports bare.
+                fileId, path: dest, mimeType: resolveDownloadMime(Buffer.alloc(0), cached.mimeType, cached.fileName),
+                sizeBytes: cached.sizeBytes, fileName: cached.fileName, note: 'already downloaded',
             });
         }
         const response = await client.requestBinary('GET', `/pub/v1/myfiles/${fileId}/data`);
         attachmentIO.writeDownload(dest, response.body);
         await cache.markAttachmentDownloaded(fileId, dest);
+        const fileName = response.suggestedFileName ?? cached.fileName;
         return jsonResponse({
             fileId,
             path: dest,
-            mimeType: response.contentType ?? cached.mimeType,
+            mimeType: resolveDownloadMime(response.body, response.contentType ?? cached.mimeType, fileName),
             sizeBytes: response.body.length,
-            fileName: response.suggestedFileName ?? cached.fileName,
+            fileName,
         });
     });
     server.registerTool('ofw_sync_messages', {
         description: 'Sync messages from OurFamilyWizard into the local cache. Returns counts per folder and a list of unread inbox messages whose bodies were NOT fetched (to avoid mark-as-read on OFW). Call ofw_get_message(id) on those to read them. EVERY call re-checks the newest page first, so new messages are picked up promptly even while an old-history backfill is still running; only then does it spend what is left of its budget advancing that backfill. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps). Sync is BOUNDED and RESUMABLE: on hosted deployments a per-call OFW-request budget (env OFW_SYNC_MAX_REQUESTS, or the maxRequests argument) caps how far one call walks; when the budget is hit the response reports done:false with a note — call again with the SAME arguments to resume. done:false means older history is still being backfilled; it does NOT mean recent messages are missing. Local installs are unbounded by default (done is always true).',
         annotations: { readOnlyHint: false },
         inputSchema: {
-            folders: z.array(z.enum(['inbox', 'sent', 'drafts'])).describe('Folders to sync (default: all three)').optional(),
+            folders: z.array(z.enum(['inbox', 'sent', 'drafts'])).min(1).describe('Folders to sync (default: all three). Must be non-empty if given — an empty list would sync nothing while reporting success.').optional(),
             fetchUnreadBodies: z.boolean().describe('If true, also fetch bodies for unread inbox messages (will mark them as read on OFW). Default false.').optional(),
             deep: z.boolean().describe('If true, walk every OFW page until empty regardless of cache state. Use to backfill gaps. Default false.').optional(),
             maxRequests: z.number().int().min(1).describe('Maximum OFW requests this single call may make before pausing. When hit, the response reports done:false — call again with the same arguments to continue. Omit to use the server default (OFW_SYNC_MAX_REQUESTS, or unbounded on local installs).').optional(),
         },
     }, async (args) => {
+        const cache = cacheProvider();
         const result = await syncAll(client, {
             folders: args.folders,
             fetchUnreadBodies: args.fetchUnreadBodies,
             deep: args.deep,
             maxRequests: args.maxRequests ?? getSyncMaxRequests(),
-        }, cacheProvider());
-        return jsonResponse(result);
+        }, cache);
+        // Freshness of the cache AS OF this sync completing — so a paused call
+        // that skipped a folder says so here too, not just in `notRefreshed`.
+        const freshness = await buildFreshness(cache, {
+            source: 'cache',
+            folders: args.folders ?? ['inbox', 'sent', 'drafts'],
+        });
+        return jsonResponse({ ...result, freshness });
+    });
+    server.registerTool('ofw_check_freshness', {
+        description: 'Cheaply confirm whether the local cache still matches OurFamilyWizard, WITHOUT running a full sync. Use this before asserting anything about current state — especially "draft X is still sitting unsent" — when a read returned serverConfirmed:false or freshness.staleness other than "fresh". Costs one OFW request for the folder check plus one per messageId. For each folder it returns the live server count next to the cached count; for each id, whether it still exists on OFW and whether its content matches the cache (compared by content revision, because OFW draft timestamps do NOT change when a draft is edited in the web app). Does not fetch bodies into the cache, does not touch attachments, and does not depend on sync state.',
+        annotations: { readOnlyHint: true },
+        inputSchema: {
+            folders: z.array(z.enum(['inbox', 'sent', 'drafts'])).min(1).describe('Folders to compare cached vs live counts for. Defaults to all three when messageIds is not given. Must be non-empty if given.').optional(),
+            messageIds: z.array(z.number()).describe(`Specific ids to verify against OFW (max ${MAX_FRESHNESS_IDS}). By default only ids present in the drafts cache are probed — see allowMarkRead.`).optional(),
+            allowMarkRead: z.boolean().describe('Default false. Probing an id that is NOT a cached draft requires fetching its detail, which marks an unread inbox message as READ on OurFamilyWizard — an irreversible change to the record. Such ids are skipped unless you set this to true.').optional(),
+        },
+    }, async (args) => {
+        const cache = cacheProvider();
+        const allowMarkRead = args.allowMarkRead ?? false;
+        const requestedIds = args.messageIds ?? [];
+        const ids = requestedIds.slice(0, MAX_FRESHNESS_IDS);
+        // Folders default to "all three" only when the caller asked about nothing
+        // else; an ids-only call shouldn't silently spend a request on folders.
+        const wantFolders = args.folders
+            ?? (requestedIds.length > 0 ? [] : ['inbox', 'sent', 'drafts']);
+        let requestsUsed = 0;
+        const folders = [];
+        if (wantFolders.length > 0) {
+            requestsUsed++;
+            const data = parseLenient(FolderCountsSchema, await client.request('GET', '/pub/v1/messageFolders?includeFolderCounts=true'), { label: 'ofw-mcp', context: 'GET /pub/v1/messageFolders (ofw_check_freshness)' });
+            const sys = data.systemFolders ?? [];
+            for (const folder of wantFolders) {
+                const entry = sys.find((x) => x.folderType === FOLDER_TYPE[folder]);
+                const serverCount = entry?.totalCount ?? entry?.messageCount ?? entry?.count ?? null;
+                const cachedCount = folder === 'drafts'
+                    ? (await cache.listDraftIds()).length
+                    : await cache.countMessages({ folder });
+                const state = await cache.getSyncState(folder);
+                const historyComplete = state !== null && state.resumePage === null;
+                // A partially backfilled folder legitimately holds fewer messages than
+                // the server, so a count mismatch there proves nothing. Report both
+                // numbers and leave the verdict null rather than crying wolf for the
+                // entire duration of a backfill.
+                const inSync = serverCount === null || !historyComplete
+                    ? null
+                    : serverCount === cachedCount;
+                folders.push({
+                    folder,
+                    existsOnServer: entry !== undefined,
+                    serverCount,
+                    cachedCount,
+                    historyComplete,
+                    lastVerifiedAt: await getFolderVerifiedAt(cache, folder),
+                    inSync,
+                    ...(inSync === null
+                        ? { note: serverCount === null
+                                ? 'OFW did not report a count for this folder, so cached-vs-server cannot be compared. Use the per-id check instead.'
+                                : 'Older history is still being backfilled, so a lower cachedCount is expected and does not indicate drift.' }
+                        : {}),
+                });
+            }
+        }
+        const items = [];
+        for (const id of ids) {
+            const cachedDraft = await cache.getDraft(id);
+            // Drafts have no read state, so probing one is genuinely side-effect
+            // free. Any other id means GET /pub/v3/messages/{id}, which marks an
+            // unread inbox message read on OFW — a permanent change to a
+            // court-visible record. Refuse by default rather than quietly doing it.
+            if (cachedDraft === null && !allowMarkRead) {
+                items.push({
+                    id,
+                    skipped: true,
+                    reason: 'NOT_A_CACHED_DRAFT',
+                    note: 'Not in the drafts cache. Verifying it requires fetching its detail from OFW, which would mark an unread inbox message as READ on OurFamilyWizard. Pass allowMarkRead:true if that is acceptable.',
+                });
+                continue;
+            }
+            requestsUsed++;
+            try {
+                const server = await fetchServerDraft(client, id);
+                const cacheRevision = cachedDraft === null ? null : draftRevision(cachedDraft);
+                if (server === null) {
+                    items.push({
+                        id,
+                        existsOnServer: false,
+                        inSync: false,
+                        cacheRevision,
+                        serverRevision: null,
+                        note: cachedDraft === null
+                            ? 'Not found on OurFamilyWizard.'
+                            : 'This draft is in the local cache but NO LONGER EXISTS on OurFamilyWizard — it was sent or deleted elsewhere. Do not describe it as still unsent.',
+                    });
+                    continue;
+                }
+                const serverRevision = draftRevision(server);
+                items.push({
+                    id,
+                    existsOnServer: true,
+                    cacheRevision,
+                    serverRevision,
+                    inSync: cacheRevision !== null && cacheRevision === serverRevision,
+                    ...(cacheRevision === null
+                        ? { note: 'Exists on OurFamilyWizard but is not in the local cache.' }
+                        : cacheRevision !== serverRevision
+                            ? { note: 'Content differs from the cache — it was edited on OurFamilyWizard since the last sync. Run ofw_sync_messages before reading or writing it.' }
+                            : {}),
+                });
+            }
+            catch (e) {
+                // A check that could not run must not read as "in sync".
+                items.push({
+                    id,
+                    error: 'FRESHNESS_CHECK_FAILED',
+                    message: e.message,
+                    inSync: null,
+                    note: 'The freshness check itself failed, so nothing is confirmed either way.',
+                });
+            }
+        }
+        const payload = {
+            checkedAt: new Date().toISOString(),
+            requestsUsed,
+            ...(folders.length > 0 ? { folders } : {}),
+            ...(items.length > 0 ? { items } : {}),
+        };
+        if (requestedIds.length > ids.length) {
+            payload.note = `Only the first ${MAX_FRESHNESS_IDS} of ${requestedIds.length} messageIds were checked (per-call cap). The remaining ${requestedIds.length - ids.length} were NOT verified — call again with the rest.`;
+        }
+        return jsonResponse(payload);
     });
 }
 // OFW's bulk-delete endpoint takes a multipart form with `messageIds`.