ofw-mcp 2.7.1 → 2.9.0

package/dist/tools/messages.js

@@ -2,11 +2,13 @@ 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 { FOLDER_TYPE, newDraftKey, persistFolderIds, probeIds, resolveDraftKey } from './lifecycle.js';
 import { getFolderVerifiedAt } from '../sync.js';
-import { isHostRenderableImage, resolveDownloadMime } from './attachments.js';
-import { getAttachmentsDir, getDefaultInlineAttachments, getSyncMaxRequests, getWriteMode } from '../config.js';
+import { buildInlineDelivery, tryExtract } from './delivery.js';
+import { resolveDownloadMime } from './attachments.js';
+import { getAllowMarkRead, getAttachmentsDir, getAutoRefreshStaleReads, getDefaultInlineAttachments, getFetchUnreadBodies, 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';
+import { ApiRecipientSchema, deriveRead, expandPath, hasRealView, jsonErrorResponse, jsonResponse, mapRecipients, postMessageAndRefetch, textResponse, verifyWriteLanded, withReadState } from './_shared.js';
 import { parseLenient } from '@chrischall/mcp-utils';
 // Schemas for the load-bearing fields of each /pub/v3 response this file
 // reads (issue #83). Loose: unknown keys pass through into cached listData.
@@ -44,7 +46,10 @@ const MessageDetailSchema = z.looseObject({
     // The detail payload carries its own owning folder ({id, name}). We read the
     // id to label a live-fetched message sent-vs-inbox instead of blindly
     // defaulting to inbox — see the folder derivation in ofw_get_message.
-    folder: z.looseObject({ id: z.number() }).optional(),
+    // Same union as ServerDraftSchema's, for the same reason — OFW types this id
+    // as a string on the folders listing and a number on message detail. Lenient
+    // here, so a mismatch only warns, but it would warn on EVERY live fetch.
+    folder: z.looseObject({ id: z.union([z.string(), z.number()]) }).optional(),
 });
 // Attachment-backfill detail fetch reads only `files`.
 const DetailFilesSchema = z.looseObject({ files: z.array(z.number()).optional() });
@@ -61,11 +66,6 @@ const FolderCountsSchema = z.looseObject({
         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.
  *
@@ -125,6 +125,106 @@ async function draftsFreshness(cache) {
         : 'unverified';
     return { freshness, serverConfirmed: cacheStatus === 'fresh', cacheStatus };
 }
+/**
+ * Description shared by every read tool's `autoRefresh` argument, so the escape
+ * hatch from an UNVERIFIED_EMPTY refusal reads identically wherever it appears.
+ */
+const AUTO_REFRESH_DESC = 'If the result comes back EMPTY from a cache that is not verified-fresh, sync the backing folders first and answer from the refreshed cache instead of refusing. Defaults to the OFW_AUTO_REFRESH env var (false unless set), in which case the call refuses with result:"UNVERIFIED_EMPTY" and names the remedy. Costs OFW requests when it fires.';
+/**
+ * Run a cached read, and never let it answer "nothing there" on the strength of
+ * a cache that cannot vouch for itself.
+ *
+ * The failure this closes: an empty result set carrying a 207-minute-old
+ * `freshness` block is shaped IDENTICALLY to a verified "nothing matched". Skim
+ * past the warning and the natural next sentence is "no, that message was never
+ * sent" — a false negative stated as fact about a court-visible record. A false
+ * negative is more dangerous than a refusal precisely because it reads as a
+ * definitive answer, so the bias is: refuse, and say how to get a real one.
+ *
+ * `autoRefresh` turns the refusal into a sync-then-retry. If that still cannot
+ * make the read verifiable (the budget paused, OFW was unreachable), the refusal
+ * fires anyway — a refresh that did not work must not be treated as one that did.
+ *
+ * Non-empty results are never touched: a stale cache that DID find something is
+ * evidence of presence, and its `freshness` block already labels its age.
+ */
+async function guardedCacheRead(o) {
+    let value = await o.read();
+    let refreshed = false;
+    const unverifiable = (v) => o.isEmpty(v) && v.freshness.staleness !== 'fresh';
+    if (unverifiable(value) && o.autoRefresh) {
+        await syncAll(o.client, {
+            folders: o.folders,
+            // Same ceiling ofw_sync_messages applies: an automatic refresh must never
+            // stamp unread inbox messages as a side effect of a list read.
+            fetchUnreadBodies: getAllowMarkRead() && getFetchUnreadBodies(),
+            maxRequests: getSyncMaxRequests(),
+        }, o.cache);
+        refreshed = true;
+        value = await o.read();
+    }
+    return { value, refreshed, unverifiedEmpty: unverifiable(value) };
+}
+/** The structured non-result returned instead of an unverifiable empty list. */
+function unverifiedEmptyResponse(input) {
+    const { freshness } = input;
+    const age = freshness.ageSeconds === null
+        ? 'it has never been checked against OurFamilyWizard'
+        : `it was last verified ${freshness.ageSeconds < 60 ? `${freshness.ageSeconds} sec` : `${Math.round(freshness.ageSeconds / 60)} min`} ago`;
+    const refreshClause = input.refreshed
+        ? ' An automatic refresh ran on this call and did NOT make the result verifiable (the sync paused or skipped this folder), so the refusal stands.'
+        : '';
+    return jsonErrorResponse({
+        result: 'UNVERIFIED_EMPTY',
+        reason: `No ${input.what} were found, but the backing cache is "${freshness.staleness}" — ${age}. Refusing to report absence from unverified data: an empty result from a stale cache is indistinguishable from a verified "nothing there", and repeating it as one asserts a false negative about a legal record.${refreshClause}`,
+        remedy: input.remedy,
+        complete: false,
+        freshness,
+        ...input.extra,
+    });
+}
+/**
+ * Decide whether fetching this message's body from OFW would stamp the record,
+ * and refuse when the caller (or the deployment) has opted out of that.
+ *
+ * Returns null to proceed, or a structured refusal to return as-is.
+ *
+ * Only ONE case actually stamps: fetching the body of an UNREAD INBOX message.
+ * Everything else is waved through, because refusing a read that changes
+ * nothing would be friction with no safety to show for it:
+ *   - a SENT message — the "First Viewed" times on it belong to the recipient,
+ *     and our own fetch never writes one;
+ *   - an already-read inbox message — the stamp exists; re-reading cannot add
+ *     a second one (`deriveRead` is monotonic, so this cannot flip back);
+ *   - a cached body — this function is never reached, the cache served it.
+ *
+ * An id with NO cached row is refused: whether it would stamp is exactly what
+ * we cannot know without making the request that stamps it. Syncing first
+ * (which reads list pages, not bodies) resolves it.
+ */
+export function markReadVerdict(cached, requested) {
+    const ceiling = getAllowMarkRead();
+    if (ceiling && (requested ?? true))
+        return null;
+    const wouldStamp = cached === null
+        || (cached.folder === 'inbox' && !deriveRead(cached));
+    if (!wouldStamp)
+        return null;
+    const because = ceiling
+        ? 'you passed allowMarkRead:false'
+        : 'this server runs with OFW_ALLOW_MARK_READ=false';
+    return jsonErrorResponse({
+        error: 'MARK_READ_BLOCKED',
+        messageId: cached?.id ?? null,
+        reason: cached === null
+            ? 'This id is not in the cache, so whether reading it would mark it read is unknowable without making the request that would.'
+            : 'This is an unread inbox message; fetching its body would mark it read on OurFamilyWizard.',
+        note: `Refused because ${because}. Reading a message for the first time stamps a "First Viewed" timestamp that your co-parent can see and that forms part of the record — it cannot be undone. To read it anyway, call again with allowMarkRead:true${ceiling ? '' : ' (which this deployment does not permit — clear OFW_ALLOW_MARK_READ to re-enable)'}.`,
+        ...(cached === null
+            ? { hint: 'Run ofw_sync_messages first: it walks list pages, not bodies, so it can tell you what this id is without stamping anything.' }
+            : { subject: cached.subject, fromUser: cached.fromUser, sentAt: cached.sentAt }),
+    });
+}
 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,
@@ -142,8 +242,8 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         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.',
-        annotations: { readOnlyHint: true },
+        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. Returns an explicit `complete` boolean describing the RESULT SET: true means "this is every message on OurFamilyWizard matching these filters as of freshness.asOf" — check it before asserting a count. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as an absence; pass autoRefresh:true to sync and answer instead.',
+        annotations: { readOnlyHint: false },
         inputSchema: {
             folderId: z.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
             page: z.number().int().min(1).describe('Page number (default 1)').optional(),
@@ -151,6 +251,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             since: z.string().describe('ISO date or datetime — only messages with sent_at >= since (inclusive)').optional(),
             until: z.string().describe('ISO date or datetime — only messages with sent_at < until (exclusive)').optional(),
             q: z.string().describe('Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.').optional(),
+            autoRefresh: z.boolean().describe(AUTO_REFRESH_DESC).optional(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
@@ -164,47 +265,84 @@ 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: [],
-                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.',
+            // A rejected argument is an ERROR, not a result. Returning `messages: []`
+            // here — even with a note attached — hands back the one shape this whole
+            // mechanism exists to eliminate: an empty list that looks like an answer.
+            return jsonErrorResponse({
+                result: 'INVALID_FOLDER',
+                reason: `folderId must be "inbox", "sent", or "both" (got ${JSON.stringify(folderArg)}). Numeric OFW folder IDs are not supported by the cache.`,
+                remedy: 'Re-call with folderId omitted (searches both) or set to one of the three accepted names.',
+                complete: false,
+                note: 'No lookup was performed. This says NOTHING about what is in the cache — do not read it as "no messages".',
             });
         }
         const cache = cacheProvider();
+        const folders = folder === undefined ? ['inbox', 'sent'] : [folder];
         const filter = { folder, since: args.since, until: args.until, q: args.q };
-        const total = await cache.countMessages(filter);
-        // Reconcile each row's read state at read time: the cached list flags can be
-        // stale (a message read after it was first scraped), so `read` is derived
-        // 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));
-        // 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 { value, refreshed, unverifiedEmpty } = await guardedCacheRead({
+            client,
+            cache,
+            folders,
+            autoRefresh: args.autoRefresh ?? getAutoRefreshStaleReads(),
+            isEmpty: (v) => v.total === 0,
+            read: async () => {
+                const total = await cache.countMessages(filter);
+                // Reconcile each row's read state at read time: the cached list flags
+                // can be stale (a message read after it was first scraped), so `read`
+                // is derived 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));
+                // 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 });
+                return { messages, total, freshness };
+            },
         });
-        const payload = { messages, total, page, size, freshness };
+        if (unverifiedEmpty) {
+            return unverifiedEmptyResponse({
+                what: 'messages matching these filters',
+                freshness: value.freshness,
+                refreshed,
+                remedy: `Call ofw_sync_messages(folders:${JSON.stringify(folders)}) and retry, or re-call this tool with autoRefresh:true. ofw_check_freshness is the cheap live alternative when you only need to confirm a specific message.`,
+                extra: { page, size, filters: { folderId: folderArg, since: args.since, until: args.until, q: args.q } },
+            });
+        }
+        const { messages, total, freshness } = value;
+        // `complete` describes the RESULT SET, not the sync: true only when this
+        // payload holds every matching message the server has. `syncComplete` /
+        // `historyComplete` in `freshness` describe the walk that filled the cache
+        // and cannot answer "have I now seen all of them?" on their own — a caller
+        // needs one boolean to check before saying "you have N messages".
+        const fullSlice = page === 1 && messages.length === total;
+        const complete = fullSlice && freshness.staleness === 'fresh' && freshness.historyComplete;
+        const payload = { messages, total, page, size, complete, freshness };
+        if (!complete) {
+            payload.completeNote = [
+                !fullSlice ? `this page holds ${messages.length} of ${total} matching cached messages` : null,
+                freshness.staleness !== 'fresh' ? `the cache is "${freshness.staleness}", so newer messages may exist on OurFamilyWizard` : null,
+                !freshness.historyComplete ? 'older history is still being backfilled, so the cache does not yet hold every message' : null,
+            ].filter((r) => r !== null)
+                .join('; ')
+                .concat('. Do not state a total or an absence from this result without resolving that first.');
+        }
         if (total === 0) {
-            payload.note = 'No messages match these filters. If you expected results, check ofw_sync_messages was run, or relax the filters.';
+            payload.note = 'No messages match these filters, and the cache IS verified-fresh for these folders — so this is a real "nothing matched", not a stale-cache artefact. If you expected results, relax the filters.';
         }
         else if (page * size < total) {
             payload.note = `Showing ${(page - 1) * size + 1}–${(page - 1) * size + messages.length} of ${total}. Increase 'page' to see more, or narrow with since/until/q.`;
         }
+        if (refreshed) {
+            payload.autoRefreshed = true;
+        }
         return jsonResponse(payload);
     });
     server.registerTool('ofw_get_message', {
-        description: 'Get a single OurFamilyWizard message OR draft by ID. Reads from local cache when available; otherwise fetches from OFW (which will mark unread inbox messages as read on OFW). For ids that match a draft (in the drafts cache), the response carries folder="drafts" and the body/subject/recipients reflect the drafts cache (which ofw_sync_messages keeps fresh) — drafts have no `fromUser`, and `sentAt`/`fetchedBodyAt` mirror the draft\'s `modifiedAt`. For inbox/sent messages, folder is "inbox" or "sent" as before.',
+        description: 'Get a single OurFamilyWizard message OR draft by ID. Reads from local cache when available; otherwise fetches from OFW — and for an UNREAD INBOX message that fetch marks it read and stamps a "First Viewed" time the co-parent can see, which is part of the record and cannot be undone. Pass allowMarkRead:false to refuse such a fetch instead (cached bodies, sent messages and already-read messages are unaffected, because none of them stamp anything). For ids that match a draft (in the drafts cache), the response carries folder="drafts" and the body/subject/recipients reflect the drafts cache (which ofw_sync_messages keeps fresh) — drafts have no `fromUser`, and `sentAt`/`fetchedBodyAt` mirror the draft\'s `modifiedAt`. For inbox/sent messages, folder is "inbox" or "sent" as before.',
         annotations: { readOnlyHint: false },
         inputSchema: {
             messageId: z.string().describe('Message ID (also accepts draft IDs — drafts are routed via the drafts cache)'),
+            allowMarkRead: z.boolean().describe('Default true (the long-standing behaviour). Set false to refuse a fetch that would mark an unread INBOX message as READ on OurFamilyWizard — an irreversible, co-parent-visible change to the record. Reads that cannot stamp anything (a cached body, a sent message, an already-read message) still succeed. The server-wide OFW_ALLOW_MARK_READ=false is a ceiling this argument cannot raise.').optional(),
         },
     }, async (args) => {
         const id = Number(args.messageId);
@@ -237,6 +375,11 @@ 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),
+                // Stable logical identity. Survives the create-then-delete id churn of
+                // editing AND the transition to sent — pass it to ofw_status to ask
+                // "what happened to the thing I was working on?". Null when this draft
+                // was never written through this tool (e.g. authored in the web app).
+                draftKey: (await cache.getDraftLineageById(draftRow.id))?.draftKey ?? null,
                 cacheStatus,
                 // False = this draft's existence and unsent status are remembered from
                 // a cache, not confirmed on OFW. Call ofw_check_freshness before
@@ -299,6 +442,14 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             const freshness = await buildFreshness(cache, { source: 'cache', folders: [row.folder] });
             return jsonResponse({ ...withReadState(row), attachments, freshness });
         }
+        // Everything above this line was served without asking OFW for a body.
+        // This is the one path that fetches one — and fetching the body of an
+        // unread INBOX message marks it read on OFW, stamping a "First Viewed"
+        // time the co-parent can see. That is a court-visible, irreversible change
+        // made as a side effect of an ordinary read, so it gets an explicit gate.
+        const markReadCheck = markReadVerdict(cached, args.allowMarkRead);
+        if (markReadCheck !== null)
+            return markReadCheck;
         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
         // only when its body was NULL) already knows its folder, so keep it.
@@ -415,6 +566,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             }, SentDetailSchema, 'ofw_send_message');
             let persisted = null;
             let verifyNote = null;
+            let sentDraftKey = null;
             if (newId !== null) {
                 verifyNote = verifyWriteLanded('message', { subject, body }, detail);
                 persisted = {
@@ -431,6 +583,21 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     listData: detail,
                 };
                 await cache.upsertMessage(persisted);
+                // Extend the draft's identity chain onto the SENT message. Without this
+                // the chain would dead-end at the last draft id and "what happened to the
+                // draft I was editing?" would answer `deleted` — technically true of that
+                // id, and the exact wrong impression. With it, resolving the key lands on
+                // the sent message and reports state:"sent" with its sentAt.
+                if (draftRef !== undefined) {
+                    const prior = await cache.getDraftLineageById(draftRef);
+                    const now = new Date().toISOString();
+                    const key = prior?.draftKey ?? newDraftKey();
+                    if (prior === null) {
+                        await cache.recordDraftLineage({ id: draftRef, draftKey: key, previousId: null, recordedAt: now });
+                    }
+                    await cache.recordDraftLineage({ id: newId, draftKey: key, previousId: draftRef, recordedAt: now });
+                    sentDraftKey = key;
+                }
                 // Link attached files to the new message in the attachments cache.
                 // We may not have full metadata if the upload happened in a prior
                 // session — fall back to what we know.
@@ -461,7 +628,9 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 await deleteOFWMessages(client, [draftRef]);
                 await cache.deleteDraft(draftRef);
             }
-            const responseObj = persisted ?? raw;
+            const responseObj = persisted === null
+                ? raw
+                : { ...persisted, ...(sentDraftKey !== null ? { draftKey: sentDraftKey, previousId: draftRef } : {}) };
             const text = responseObj ? JSON.stringify(responseObj, null, 2) : 'Message sent successfully.';
             const notes = [rewriteNote, verifyNote, unconfirmedNote].filter((n) => n !== null).join('\n\n');
             return textResponse(notes ? `${notes}\n\n${text}` : text);
@@ -480,10 +649,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             server = await fetchServerDraft(client, draftId);
         }
         catch (e) {
-            // fetchServerDraft funnels every non-404 failure into DraftFreshnessError,
-            // so anything landing here means the check could not RUN. That is not
-            // permission to proceed: a transient 5xx must not degrade into a blind
-            // overwrite.
+            // Anything landing here means the check could not RUN. Most failures
+            // arrive as DraftFreshnessError from fetchServerDraft, but not all of
+            // them: a strict parseLenient mismatch on the server draft throws
+            // McpToolError instead. Both are caught, and both abort — which is the
+            // point. A failed check is not permission to proceed: a transient 5xx
+            // must not degrade into a blind overwrite. (The cast below only reads
+            // `.message`, which every Error carries.)
             const reason = e.message;
             if (force) {
                 return { ok: true, note: `WARNING: force:true — proceeded with ${action} on draft ${draftId} even though its current state could not be read from OurFamilyWizard (${reason}). Any newer server-side version was destroyed and is NOT recoverable from this response.` };
@@ -532,38 +704,72 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         };
     }
     server.registerTool('ofw_list_drafts', {
-        description: 'List draft messages from the local OurFamilyWizard cache. Call ofw_sync_messages first if the cache is empty.',
-        annotations: { readOnlyHint: true },
+        description: 'List draft messages from the local OurFamilyWizard cache. Returns an explicit `complete` boolean describing the RESULT SET: true means "these are ALL the drafts on OurFamilyWizard as of freshness.asOf" — check it before saying "you have N drafts". Each draft carries its `draftKey` (stable across the create-then-delete churn of editing) when one is known. An empty result from a cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY"); pass autoRefresh:true to sync and answer instead. For a live, one-call answer prefer ofw_status(includeDraftInventory:true).',
+        annotations: { readOnlyHint: false },
         inputSchema: {
             page: z.number().int().min(1).describe('Page number (default 1)').optional(),
             size: z.number().int().min(1).describe('Drafts per page (default 50)').optional(),
+            autoRefresh: z.boolean().describe(AUTO_REFRESH_DESC).optional(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
         const cache = cacheProvider();
-        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 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: [],
-                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 { value, refreshed, unverifiedEmpty } = await guardedCacheRead({
+            client,
+            cache,
+            folders: ['drafts'],
+            autoRefresh: args.autoRefresh ?? getAutoRefreshStaleReads(),
+            isEmpty: (v) => v.total === 0,
+            read: async () => {
+                const { freshness, serverConfirmed, cacheStatus } = await draftsFreshness(cache);
+                const rows = await cache.listDrafts({ page, size });
+                const total = await cache.countDrafts();
+                // One batch lookup for the whole page — on the Durable Object backend a
+                // per-draft lineage read would be a subrequest each.
+                const keyById = new Map((await cache.getDraftLineageByIds(rows.map((d) => d.id))).map((l) => [l.id, l.draftKey]));
+                // Every draft carries the concurrency token to echo back on a write, its
+                // stable identity across edits, and whether the last sync actually
+                // compared this cache against OFW.
+                const drafts = rows.map((d) => ({
+                    ...d,
+                    revision: draftRevision(d),
+                    draftKey: keyById.get(d.id) ?? null,
+                    cacheStatus,
+                    serverConfirmed,
+                    asOf: freshness.asOf,
+                }));
+                return { drafts, total, freshness, serverConfirmed };
+            },
+        });
+        if (unverifiedEmpty) {
+            return unverifiedEmptyResponse({
+                what: 'drafts',
+                freshness: value.freshness,
+                refreshed,
+                remedy: 'Call ofw_sync_messages(folders:["drafts"]) and retry, re-call with autoRefresh:true, or use ofw_status(includeDraftInventory:true) for a single live answer.',
+                extra: { page, size },
             });
         }
-        const payload = { drafts, freshness };
+        const { drafts, total, freshness, serverConfirmed } = value;
+        // True only when this payload IS the full server-side draft set: verified
+        // against OFW inside the freshness window AND not a slice of a larger list.
+        const fullSlice = page === 1 && drafts.length === total;
+        const complete = serverConfirmed && fullSlice;
+        const payload = { drafts, total, page, size, complete, freshness };
+        if (!complete) {
+            payload.completeNote = [
+                !fullSlice ? `this page holds ${drafts.length} of ${total} cached drafts` : null,
+                !serverConfirmed ? 'the drafts cache has not been confirmed against OurFamilyWizard inside the freshness window' : null,
+            ].filter((r) => r !== null)
+                .join('; ')
+                .concat('. Do NOT state a draft count from this result — call ofw_status(includeDraftInventory:true) for a live, complete one.');
+        }
         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.';
+            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, deleted or SENT in the OFW web app bump no timestamp, so the cache cannot detect it on its own. Call ofw_status / 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.';
+        }
+        if (refreshed) {
+            payload.autoRefreshed = true;
         }
         return jsonResponse(payload);
     });
@@ -628,6 +834,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             let replaceNote = null;
             let verifyNote = null;
             let newRevision = null;
+            let draftKey = 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 = [];
@@ -655,11 +862,48 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 // 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);
+                // Carry the logical identity across the id change. Replacing a draft mints
+                // a NEW OFW id every time (create-then-delete — see the note below), so
+                // ten edits produced ten unrelated ids and there was no way to ask what
+                // became of the one you started with. The key is minted on first sight —
+                // including retroactively for the draft being replaced, so a draft that
+                // predates this mechanism joins a chain the moment it is edited.
+                const now = new Date().toISOString();
+                if (args.messageId !== undefined) {
+                    const prior = await cache.getDraftLineageById(args.messageId);
+                    if (prior !== null) {
+                        draftKey = prior.draftKey;
+                    }
+                    else {
+                        draftKey = newDraftKey();
+                        await cache.recordDraftLineage({
+                            id: args.messageId, draftKey, previousId: null, recordedAt: now,
+                        });
+                    }
+                }
+                else {
+                    draftKey = newDraftKey();
+                }
+                await cache.recordDraftLineage({
+                    id: newId,
+                    draftKey,
+                    previousId: args.messageId ?? null,
+                    recordedAt: now,
+                });
                 // 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.`);
+                    // Two different outcomes reach this branch, and they need different
+                    // warnings. OFW either DROPPED the link (null) or RE-TARGETED it to
+                    // another message in the thread. Describing both as "did not thread
+                    // this draft (its inReplyTo/showContext will be empty)" contradicted
+                    // the non-null inReplyTo the same response echoes — and a warning the
+                    // caller can see is false is a warning it learns to skip.
+                    const outcome = effectiveReplyTo === null
+                        ? 'OurFamilyWizard did not thread this draft (its inReplyTo/showContext will be empty). The subject and body were saved; only the reply linkage was dropped.'
+                        : `OurFamilyWizard re-targeted the reply to message ${effectiveReplyTo} instead. The draft IS threaded — to that message, not the one requested — and the inReplyTo in this response reflects where it actually landed.`;
+                    warnings.push(`replyToId was requested as ${resolvedReplyTo}${rewrittenFrom} but the saved draft came back with replyToId ${effectiveReplyTo === null ? 'null' : effectiveReplyTo} — ${outcome} 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
@@ -703,6 +947,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     ...persisted,
                     inReplyTo: persisted.replyToId,
                     revision: newRevision,
+                    // The id above is volatile — it changes on every edit. `draftKey` is
+                    // not: pass it to ofw_status to resolve the chain's CURRENT id, or to
+                    // find out that the draft was sent and when.
+                    draftKey,
+                    previousId: args.messageId ?? null,
                     cacheStatus: 'fresh',
                     serverConfirmed: true,
                     ...(warnings.length > 0 ? { warnings } : {}),
@@ -742,28 +991,49 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             return textResponse(guard.note ? `${guard.note}\n\n${text}` : text);
         });
     server.registerTool('ofw_get_unread_sent', {
-        description: 'List sent messages that have not been read by one or more recipients. Reads from local cache; call ofw_sync_messages first if cache is stale.',
-        annotations: { readOnlyHint: true },
+        description: 'List sent messages that have not been read by one or more recipients. Reads from local cache. Returns `complete` describing whether every sent message was scanned. An empty SENT cache that is not verified-fresh is REFUSED (result:"UNVERIFIED_EMPTY") rather than reported as "nothing sent"; pass autoRefresh:true to sync and answer instead.',
+        annotations: { readOnlyHint: false },
         inputSchema: {
             page: z.number().int().min(1).describe('Page (default 1)').optional(),
             size: z.number().int().min(1).describe('Per page (default 50)').optional(),
+            autoRefresh: z.boolean().describe(AUTO_REFRESH_DESC).optional(),
         },
     }, async (args) => {
         const page = args.page ?? 1;
         const size = args.size ?? 50;
         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({
-                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 { value, refreshed, unverifiedEmpty } = await guardedCacheRead({
+            client,
+            cache,
+            folders: ['sent'],
+            autoRefresh: args.autoRefresh ?? getAutoRefreshStaleReads(),
+            // The guard is about the CACHE being empty, not the verdict. "You have
+            // no sent messages" is an absence claim a stale cache cannot support;
+            // "all of them are read" is a verdict over messages we did see, and it is
+            // labelled by `freshness` and `complete` as before.
+            isEmpty: (v) => v.total === 0,
+            read: async () => {
+                const sent = await cache.listMessages({ folder: 'sent', page, size });
+                const total = await cache.countMessages({ folder: 'sent' });
+                // "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'] });
+                return { sent, total, freshness };
+            },
+        });
+        if (unverifiedEmpty) {
+            return unverifiedEmptyResponse({
+                what: 'sent messages in the local cache',
+                freshness: value.freshness,
+                refreshed,
+                remedy: 'Call ofw_sync_messages(folders:["sent"]) and retry, or re-call with autoRefresh:true.',
+                extra: { page, size },
             });
         }
+        const { sent, total, freshness } = value;
+        const fullSlice = page === 1 && sent.length === total;
+        const complete = fullSlice && freshness.staleness === 'fresh' && freshness.historyComplete;
         const unread = [];
         for (const msg of sent) {
             const unreadBy = msg.recipients.filter((r) => r.viewedAt === null).map((r) => r.name);
@@ -771,14 +1041,17 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                 unread.push({ id: msg.id, subject: msg.subject, sentAt: msg.sentAt, unreadBy });
             }
         }
+        const payload = { unread, scanned: sent.length, total, complete, freshness };
+        if (!complete) {
+            payload.completeNote = `This verdict covers the ${sent.length} of ${total} cached sent messages on this page${freshness.staleness === 'fresh' ? '' : `, from a cache that is "${freshness.staleness}"`}. It is not a statement about every message you have sent.`;
+        }
         if (unread.length === 0) {
-            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.',
-            });
+            payload.message = 'Every sent message scanned had been read as of the timestamp in `freshness.asOf`. A recipient may have read — or not read — a message since without the cache hearing about it.';
         }
-        return jsonResponse({ unread, freshness });
+        if (refreshed) {
+            payload.autoRefreshed = true;
+        }
+        return jsonResponse(payload);
     });
     if (allowDrafts)
         server.registerTool('ofw_upload_attachment', {
@@ -825,13 +1098,16 @@ 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 — 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).',
+        description: 'Download an OFW message attachment by fileId and return content you can actually read. Inline delivery walks a ladder and returns the first rung that works: (1) host-renderable images (PNG/JPEG/GIF/WEBP) come back as ImageContent; (2) .xlsx/.csv/.tsv, .pdf, .docx, .pptx and text files come back as EXTRACTED CONTENT — per-sheet CSV, per-page/slide text, document text — in the response JSON under `extracted`; (3) anything else comes back as an EmbeddedResource blob of the raw bytes. The meta block names the rung as `deliveredVia` and, when it falls through to bytes, lists what was tried in `deliveryAttempts`. Reported mime types are always normalized to a bare media type (no charset/name parameters). In disk mode the bytes are saved to ~/Downloads/ofw-mcp/ and the response carries the absolute path; pass extract:true to ALSO get the extracted content in that response. The default for `inline` can be flipped server-side via the OFW_INLINE_ATTACHMENTS env var. On a hosted deployment with no filesystem, disk mode is unavailable, so inline is forced (forcedInline:true) rather than failing — a saveTo path never costs you the content. 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 (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(),
+            inline: z.boolean().describe('If true, return content inline as MCP content blocks 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 content is 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(),
+            extract: z.boolean().describe('Whether to extract readable content from the file. Default: on for inline delivery of any non-image type, off in disk mode. Set false to get the raw bytes inline instead of extracted text (e.g. to hash or re-upload the file); set true in disk mode to get both the saved path and the extracted content.').optional(),
+            maxChars: z.number().int().min(500).max(500_000).describe('Ceiling on extracted characters (default 50000). Over it, content is clipped on a row/line boundary, `truncated` is set, and anything dropped whole is listed in `extracted.omitted`.').optional(),
+            parts: z.string().describe('Which sheets / slides / pages to extract, e.g. "1-3,5" (1-based positions) or a sheet name like "2026". A bare number matches either a position or a name. Omit for everything. Unselected parts are listed in `extracted.omitted`.').optional(),
         },
     }, async (args) => {
         const fileId = args.fileId;
@@ -843,6 +1119,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         // response is honest about it instead of silently ignoring the argument.
         const inline = requestedInline || !attachmentIO.supportsDisk;
         const forcedInline = inline && !requestedInline;
+        const deliveryOptions = { extract: args.extract, maxChars: args.maxChars, parts: args.parts };
         let cached = await cache.getAttachment(fileId);
         if (!cached) {
             // Not in cache. Fetch metadata and store under the messageId=0
@@ -871,25 +1148,12 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             // 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 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: {
-                            uri: `ofw://attachment/${fileId}/${encodeURIComponent(fileName)}`,
-                            mimeType,
-                            blob: base64,
-                        } }] };
+            // The ladder decides between rendering, extracted content, and raw bytes
+            // — see src/tools/delivery.ts. Whatever the host can draw, the caller
+            // ends up holding something readable.
+            return await buildInlineDelivery({
+                fileId, fileName, mimeType, bytes, forcedInline, options: deliveryOptions,
+            });
         }
         let dest;
         // The filename comes from OFW file metadata — i.e. it is controlled by the
@@ -906,25 +1170,38 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         else {
             dest = join(getAttachmentsDir(), `${fileId}-${safeName}`);
         }
+        // Disk mode extracts only on request: the caller already has a real file to
+        // open, so extraction is an add-on here rather than the point.
+        const extractOnDisk = args.extract === true;
         if (!args.force && cached.downloadedPath === dest) {
-            return jsonResponse({
-                // 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',
-            });
+            // Nothing was re-fetched, so an extraction has to come off the copy on
+            // disk. If that copy has gone missing, fall through and download again
+            // rather than answering "already downloaded" with no content.
+            const onDisk = extractOnDisk ? attachmentIO.readDownloaded(dest) : null;
+            if (!extractOnDisk || onDisk) {
+                // No bytes on hand for the plain no-op case: normalize the
+                // cached/extension MIME (an empty buffer sniffs nothing) so a stored
+                // `image/png;charset=…` still reports bare.
+                const mimeType = resolveDownloadMime(onDisk ?? Buffer.alloc(0), cached.mimeType, cached.fileName);
+                return jsonResponse({
+                    fileId, path: dest, mimeType,
+                    sizeBytes: cached.sizeBytes, fileName: cached.fileName, note: 'already downloaded',
+                    ...(onDisk ? await tryExtract(onDisk, mimeType, cached.fileName, deliveryOptions) : {}),
+                });
+            }
         }
         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;
+        const mimeType = resolveDownloadMime(response.body, response.contentType ?? cached.mimeType, fileName);
         return jsonResponse({
             fileId,
             path: dest,
-            mimeType: resolveDownloadMime(response.body, response.contentType ?? cached.mimeType, fileName),
+            mimeType,
             sizeBytes: response.body.length,
             fileName,
+            ...(extractOnDisk ? await tryExtract(response.body, mimeType, fileName, deliveryOptions) : {}),
         });
     });
     server.registerTool('ofw_sync_messages', {
@@ -932,7 +1209,7 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         annotations: { readOnlyHint: false },
         inputSchema: {
             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(),
+            fetchUnreadBodies: z.boolean().describe('If true, also fetch bodies for unread inbox messages — which marks each one READ on OurFamilyWizard and stamps a co-parent-visible "First Viewed" time that cannot be undone. Defaults to the OFW_FETCH_UNREAD_BODIES env var (false unless set), and is forced off entirely when OFW_ALLOW_MARK_READ=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(),
         },
@@ -940,7 +1217,10 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         const cache = cacheProvider();
         const result = await syncAll(client, {
             folders: args.folders,
-            fetchUnreadBodies: args.fetchUnreadBodies,
+            // Default from OFW_FETCH_UNREAD_BODIES (false unless set), and capped by
+            // the OFW_ALLOW_MARK_READ ceiling — fetching those bodies is exactly what
+            // stamps a First Viewed time on every unread message it touches.
+            fetchUnreadBodies: getAllowMarkRead() && (args.fetchUnreadBodies ?? getFetchUnreadBodies()),
             deep: args.deep,
             maxRequests: args.maxRequests ?? getSyncMaxRequests(),
         }, cache);
@@ -953,16 +1233,19 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         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 },
+        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". 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 it returns a LIVE lifecycle `state` — "draft" | "sent" | "received" | "deleted" | "unknown" — alongside `folder`, `sentAt`, `existsOnServer` and a content comparison. `state` is the field that answers "is this still a draft?": a draft that has been SENT still exists on the server, so existsOnServer:true never distinguished the two. A cached draft whose state is no longer "draft" reports inSync:false even when its text is byte-identical. Content is compared by revision hash, 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. For draftKeys, or a full live draft inventory, use ofw_status.',
+        annotations: { readOnlyHint: false },
         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(),
+            messageIds: z.array(z.number()).describe(`Specific ids to verify against OFW (max ${MAX_FRESHNESS_IDS}). Ids cached as drafts, as sent messages, or as already-read inbox messages are probed freely — none of those can stamp the record. Anything else is skipped — see allowMarkRead.`).optional(),
+            allowMarkRead: z.boolean().describe('Default false. Probing an id whose cached state cannot rule out an unread INBOX message requires fetching its detail, which marks it READ on OurFamilyWizard and stamps a co-parent-visible "First Viewed" time — irreversible. Such ids are skipped (reason:"WOULD_MARK_READ") unless you set this to true. The server-wide OFW_ALLOW_MARK_READ=false is a ceiling this cannot raise.').optional(),
         },
     }, async (args) => {
         const cache = cacheProvider();
-        const allowMarkRead = args.allowMarkRead ?? false;
+        // The server-wide ceiling wins: a per-call allowMarkRead:true (or an
+        // instruction injected into one) must not be able to stamp the record on a
+        // deployment configured to never do so.
+        const allowMarkRead = getAllowMarkRead() && (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
@@ -975,6 +1258,11 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
             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 ?? [];
+            // Take the folder ids while we have them. Without this a call asking
+            // about BOTH folders and ids, on a cache that has never synced, fetched
+            // this exact endpoint twice — once here for the counts and again inside
+            // probeIds' ensureFolderIdMap for the ids it already had in hand.
+            await persistFolderIds(cache, sys);
             for (const folder of wantFolders) {
                 const entry = sys.find((x) => x.folderType === FOLDER_TYPE[folder]);
                 const serverCount = entry?.totalCount ?? entry?.messageCount ?? entry?.count ?? null;
@@ -982,7 +1270,13 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     ? (await cache.listDraftIds()).length
                     : await cache.countMessages({ folder });
                 const state = await cache.getSyncState(folder);
-                const historyComplete = state !== null && state.resumePage === null;
+                // Never synced at all is a DIFFERENT state from "backfill in progress",
+                // and both leave historyComplete false. Conflating them told the caller
+                // that older history was still being backfilled for a folder whose
+                // backfill had never started — advice that reads as "wait it out" when
+                // the real answer is "run a sync".
+                const neverSynced = state === null;
+                const historyComplete = !neverSynced && 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
@@ -1001,69 +1295,19 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
                     ...(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.' }
+                                : neverSynced
+                                    ? 'This folder has never been synced, so the cache holds nothing to compare. Run ofw_sync_messages.'
+                                    : '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.',
-                });
-            }
-        }
+        // One folder-id resolve for the whole batch, and only when at least one id
+        // is actually going to be probed — a call whose every id is refused for
+        // mark-read reasons must cost nothing at all.
+        const probed = await probeIds(client, cache, ids, { allowMarkRead });
+        requestsUsed += probed.requests;
+        const items = probed.items;
         const payload = {
             checkedAt: new Date().toISOString(),
             requestsUsed,
@@ -1075,6 +1319,156 @@ export function registerMessageTools(server, client, cacheProvider, attachmentIO
         }
         return jsonResponse(payload);
     });
+    server.registerTool('ofw_status', {
+        description: 'ONE live call that answers "where does everything stand?". This is the call that should back any status summary about drafts or specific messages — never session memory, and never a cached read alone. With no arguments it returns the FULL current draft inventory, verified against OurFamilyWizard. Pass ids and/or draftKeys to get each one\'s live lifecycle `state` ("draft" | "sent" | "received" | "deleted" | "unknown") with `sentAt` and `viewedAt`. A draftKey is the stable identity ofw_save_draft returns: editing a draft mints a new OFW id every time (create-then-delete), so the key is the only way to ask "what happened to the thing I was working on?" — it resolves to the chain\'s current id and keeps resolving after the draft is SENT (state:"sent" with sentMessageId). The top-level `complete` is true ONLY when every part of this snapshot was verified live; if it is false, do not state a draft count or a lifecycle claim from this payload.',
+        annotations: { readOnlyHint: false },
+        inputSchema: {
+            ids: z.array(z.number()).describe(`Message/draft ids to resolve to a live state (combined with draftKeys, max ${MAX_FRESHNESS_IDS} probes per call).`).optional(),
+            draftKeys: z.array(z.string()).describe('Stable draft keys (from ofw_save_draft / ofw_list_drafts) to resolve to their CURRENT id and state.').optional(),
+            includeDraftInventory: z.boolean().describe('Return the full current draft list, verified against OurFamilyWizard first. Defaults to TRUE when neither ids nor draftKeys is given (so a bare ofw_status() is a complete status snapshot), otherwise false.').optional(),
+            allowMarkRead: z.boolean().describe('Default false. An id whose cached state cannot rule out an unread INBOX message can only be probed by fetching its detail, which marks it READ on OurFamilyWizard — irreversible and co-parent-visible. Those are skipped unless this is true. Cached drafts, sent messages and already-read messages are always probed. Capped by OFW_ALLOW_MARK_READ.').optional(),
+        },
+    }, async (args) => {
+        const cache = cacheProvider();
+        const allowMarkRead = getAllowMarkRead() && (args.allowMarkRead ?? false);
+        const requestedIds = args.ids ?? [];
+        const requestedKeys = args.draftKeys ?? [];
+        // A bare ofw_status() is meant to be the "here is where everything stands"
+        // call, so it defaults to the inventory. Asking about specific ids does not
+        // silently spend a drafts sync you did not ask for.
+        const wantInventory = args.includeDraftInventory
+            ?? (requestedIds.length === 0 && requestedKeys.length === 0);
+        const allTargets = [
+            ...requestedIds.map((id) => ({ kind: 'id', id })),
+            ...requestedKeys.map((draftKey) => ({ kind: 'draftKey', draftKey })),
+        ];
+        const targets = allTargets.slice(0, MAX_FRESHNESS_IDS);
+        const truncated = allTargets.length - targets.length;
+        // Nothing asked for, nothing checked — so there is nothing to be complete
+        // ABOUT. Returning `complete: true` here would be a reassuring-looking
+        // payload that verified precisely nothing, which is the failure mode this
+        // whole tool exists to remove.
+        if (!wantInventory && targets.length === 0) {
+            return jsonErrorResponse({
+                result: 'NOTHING_REQUESTED',
+                reason: 'ofw_status was called with includeDraftInventory:false and no ids or draftKeys, so nothing was checked.',
+                remedy: 'Call ofw_status() with no arguments for the full draft inventory, or pass ids / draftKeys.',
+                complete: false,
+            });
+        }
+        let probeRequests = 0;
+        const incomplete = [];
+        // ── Draft inventory ────────────────────────────────────────────────────
+        let drafts;
+        let inventoryComplete = true;
+        let inventoryFreshness;
+        if (wantInventory) {
+            const sync = await syncAll(client, {
+                folders: ['drafts'],
+                maxRequests: getSyncMaxRequests(),
+            }, cache);
+            // `refreshed` is the only honest signal that the walk actually diffed
+            // against OFW. A budget-paused walk applies nothing and returns no count
+            // — reporting its inventory as complete would be the same lie as
+            // `drafts: 0` from a deferred sync.
+            inventoryComplete = sync.refreshed.includes('drafts');
+            const { freshness, cacheStatus, serverConfirmed } = await draftsFreshness(cache);
+            inventoryFreshness = freshness;
+            if (!serverConfirmed)
+                inventoryComplete = false;
+            const total = await cache.countDrafts();
+            const rows = await cache.listDrafts({ page: 1, size: Math.max(total, 1) });
+            const keyById = new Map((await cache.getDraftLineageByIds(rows.map((d) => d.id))).map((l) => [l.id, l.draftKey]));
+            drafts = rows.map((d) => ({
+                id: d.id,
+                draftKey: keyById.get(d.id) ?? null,
+                subject: d.subject,
+                revision: draftRevision(d),
+                modifiedAt: d.modifiedAt,
+                recipients: d.recipients,
+                replyToId: d.replyToId,
+                cacheStatus,
+            }));
+            if (!inventoryComplete) {
+                incomplete.push('the drafts folder was not fully verified against OurFamilyWizard on this call (the request budget paused the walk), so this inventory may be missing or misreporting drafts');
+            }
+        }
+        // ── Per-id / per-key lifecycle ─────────────────────────────────────────
+        const requested = [];
+        if (targets.length > 0) {
+            // Resolve keys to ids first so a key and a bare id naming the SAME
+            // message are probed once, not twice.
+            const resolved = new Map();
+            for (const t of targets) {
+                if (t.kind === 'draftKey' && !resolved.has(t.draftKey)) {
+                    resolved.set(t.draftKey, await resolveDraftKey(cache, t.draftKey));
+                }
+            }
+            const toProbe = new Set();
+            for (const t of targets) {
+                if (t.kind === 'id')
+                    toProbe.add(t.id);
+                else {
+                    const chain = resolved.get(t.draftKey);
+                    if (chain !== null && chain !== undefined)
+                        toProbe.add(chain.currentId);
+                }
+            }
+            const probed = await probeIds(client, cache, [...toProbe], { allowMarkRead });
+            probeRequests += probed.requests;
+            const probes = new Map(probed.items.map((item) => [item.id, item]));
+            for (const t of targets) {
+                if (t.kind === 'id') {
+                    requested.push(decorate(probes.get(t.id)));
+                    continue;
+                }
+                const chain = resolved.get(t.draftKey);
+                if (chain === null || chain === undefined) {
+                    requested.push({
+                        draftKey: t.draftKey,
+                        state: 'unknown',
+                        error: 'UNKNOWN_DRAFT_KEY',
+                        note: 'This draftKey has never been recorded in the local cache, so it cannot be resolved to a message id. Draft keys are minted by ofw_save_draft; a cache rebuilt or opened on another machine will not know an older key.',
+                    });
+                    continue;
+                }
+                requested.push({
+                    draftKey: t.draftKey,
+                    currentId: chain.currentId,
+                    previousIds: chain.ids.slice(0, -1),
+                    ...decorate(probes.get(chain.currentId)),
+                });
+            }
+            for (const entry of requested) {
+                if (entry.skipped === true || entry.error !== undefined || entry.state === 'unknown') {
+                    incomplete.push(`id/key ${String(entry.draftKey ?? entry.id)} could not be resolved to a confirmed live state`);
+                }
+            }
+        }
+        if (truncated > 0) {
+            incomplete.push(`${truncated} of ${allTargets.length} requested ids/draftKeys were not probed (per-call cap of ${MAX_FRESHNESS_IDS})`);
+        }
+        const complete = incomplete.length === 0;
+        return jsonResponse({
+            checkedAt: new Date().toISOString(),
+            probeRequests,
+            ...(drafts !== undefined ? { drafts, draftCount: drafts.length, draftInventoryComplete: inventoryComplete } : {}),
+            ...(requested.length > 0 ? { requested } : {}),
+            complete,
+            ...(complete
+                ? {}
+                : { incompleteReasons: incomplete, note: 'complete:false — this snapshot is NOT a verified statement of current state. Do not report a draft count or say whether something was sent from it; resolve the reasons above (usually by calling ofw_sync_messages, or re-calling with allowMarkRead:true) and ask again.' }),
+            ...(inventoryFreshness !== undefined ? { freshness: inventoryFreshness } : {}),
+        });
+    });
+}
+/**
+ * Add the derived fields a status entry wants on top of a raw lifecycle probe.
+ * `sentMessageId` names the id the message ended up as once sent — the answer to
+ * "the draft I was editing went where?" — and only exists for a `sent` verdict.
+ */
+function decorate(item) {
+    return item.state === 'sent' ? { ...item, sentMessageId: item.id } : { ...item };
 }
 // OFW's bulk-delete endpoint takes a multipart form with `messageIds`.
 // Used by both ofw_delete_draft and ofw_send_message (draft cleanup).