ofw-mcp 2.6.7 → 2.7.1

package/dist/bundle.js

@@ -38407,7 +38407,7 @@ async function loginWithPassword(username, password) {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.6.7",
+  version: "2.7.1",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -38449,13 +38449,13 @@ var package_default = {
     zod: "^4.4.3"
   },
   devDependencies: {
-    "@chrischall/mcp-connector": "^1.0.0",
+    "@chrischall/mcp-connector": "^1.1.1",
     "@cloudflare/vitest-pool-workers": "^0.18.4",
     "@cloudflare/workers-oauth-provider": "^0.8.1",
     "@cloudflare/workers-types": "^5.20260708.1",
     "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.7",
-    agents: "^0.17.3",
+    agents: "^0.19.0",
     esbuild: "^0.28.0",
     typescript: "^7.0.2",
     vitest: "^4.1.7",
@@ -38880,10 +38880,11 @@ async function walkPages(client2, folder, folderId, opts, store) {
   let page = opts.startPage;
   let newestId = null;
   let synced = 0;
+  let pagesFetched = 0;
   const unread = [];
   while (true) {
     if (!budget.take()) {
-      return { synced, unread, newestId, done: false, nextPage: page };
+      return { synced, unread, newestId, pagesFetched, done: false, nextPage: page };
     }
     const path = `/pub/v3/messages?folders=${encodeURIComponent(folderId)}&page=${page}&size=50&sort=date&sortDirection=desc`;
     const list = parseLenient(
@@ -38891,9 +38892,10 @@ async function walkPages(client2, folder, folderId, opts, store) {
       await client2.request("GET", path),
       { label: "ofw-mcp", context: `GET /pub/v3/messages?folders={${folder}}` }
     );
+    pagesFetched++;
     const items = list.data ?? [];
     if (items.length === 0) {
-      return { synced, unread, newestId, done: true, nextPage: null };
+      return { synced, unread, newestId, pagesFetched, done: true, nextPage: null };
     }
     const existingById = new Map(
       (await store.getMessages(items.map((it) => it.id))).map((row) => [row.id, row])
@@ -38972,10 +38974,10 @@ async function walkPages(client2, folder, folderId, opts, store) {
     }
     await store.upsertMessages(toUpsert);
     if (pageBudgetHit) {
-      return { synced, unread, newestId, done: false, nextPage: page };
+      return { synced, unread, newestId, pagesFetched, done: false, nextPage: page };
     }
     if (opts.stopAtCachedPage && !pageHadNewItem) {
-      return { synced, unread, newestId, done: true, nextPage: page };
+      return { synced, unread, newestId, pagesFetched, done: true, nextPage: page };
     }
     page++;
   }
@@ -38997,7 +38999,11 @@ async function syncMessageFolder(client2, folder, folderId, opts, store) {
   let resumePage;
   if (!fwd.done) {
     done = false;
-    resumePage = savedResume === null ? fwd.nextPage : Math.min(fwd.nextPage, savedResume);
+    if (fwd.pagesFetched === 0) {
+      resumePage = savedResume;
+    } else {
+      resumePage = savedResume === null ? fwd.nextPage : Math.min(fwd.nextPage, savedResume);
+    }
   } else if (fwd.nextPage === null) {
     done = true;
     resumePage = null;
@@ -39017,12 +39023,10 @@ async function syncMessageFolder(client2, folder, folderId, opts, store) {
     done = bf.done;
     resumePage = bf.done ? null : bf.nextPage;
   }
-  await store.setSyncState(folder, {
-    lastSyncAt: (/* @__PURE__ */ new Date()).toISOString(),
-    newestId,
-    resumePage
-  });
-  return { synced, unread, done };
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await store.setSyncState(folder, { lastSyncAt: now, newestId, resumePage });
+  if (fwd.done) await markFolderVerified(store, folder, now);
+  return { synced, unread, done, verified: fwd.done };
 }
 var DraftListItemSchema = external_exports.looseObject({
   id: external_exports.number(),
@@ -39040,10 +39044,27 @@ var DRAFTS_CACHE_STATUS_KEY = "drafts_cache_status";
 async function getDraftsCacheStatus(store) {
   return await store.getMeta(DRAFTS_CACHE_STATUS_KEY) === "fresh" ? "fresh" : "unverified";
 }
+async function setDraftsCacheStatus(store, status) {
+  await store.setMeta(DRAFTS_CACHE_STATUS_KEY, status);
+}
+function folderVerifiedAtKey(folder) {
+  return `folder_verified_at:${folder}`;
+}
+async function getFolderVerifiedAt(store, folder) {
+  return await store.getMeta(folderVerifiedAtKey(folder)) ?? null;
+}
+async function markFolderVerified(store, folder, at = (/* @__PURE__ */ new Date()).toISOString()) {
+  await store.setMeta(folderVerifiedAtKey(folder), at);
+}
 async function syncDrafts(client2, draftsFolderId, store, budget) {
   const b = budget ?? makeBudget(Number.POSITIVE_INFINITY);
   const defer = async () => {
-    await store.setMeta(DRAFTS_CACHE_STATUS_KEY, "unverified");
+    await setDraftsCacheStatus(store, "unverified");
+    await store.setSyncState("drafts", {
+      lastSyncAt: (/* @__PURE__ */ new Date()).toISOString(),
+      newestId: null,
+      resumePage: null
+    });
     return { synced: 0, done: false };
   };
   const items = [];
@@ -39096,7 +39117,10 @@ async function syncDrafts(client2, draftsFolderId, store, budget) {
   for (const id of await store.listDraftIds()) {
     if (!seenIds.has(id)) await store.deleteDraft(id);
   }
-  await store.setMeta(DRAFTS_CACHE_STATUS_KEY, "fresh");
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  await setDraftsCacheStatus(store, "fresh");
+  await store.setSyncState("drafts", { lastSyncAt: now, newestId: null, resumePage: null });
+  await markFolderVerified(store, "drafts", now);
   return { synced, done: true };
 }
 async function syncAll(client2, opts, store) {
@@ -39112,6 +39136,16 @@ async function syncAll(client2, opts, store) {
   let unreadInbox = [];
   let done = true;
   let draftsUnverified = false;
+  const refreshed = [];
+  const notRefreshed = [];
+  const record2 = (folder, verified, count) => {
+    if (verified) {
+      synced[folder] = count;
+      refreshed.push(folder);
+    } else {
+      notRefreshed.push(folder);
+    }
+  };
   for (const folder of folders) {
     if (folder === "inbox") {
       const r = await syncMessageFolder(client2, "inbox", ids.inbox, {
@@ -39119,7 +39153,7 @@ async function syncAll(client2, opts, store) {
         deep: opts.deep ?? false,
         budget
       }, store);
-      synced.inbox = r.synced;
+      record2("inbox", r.verified, r.synced);
       unreadInbox = r.unread;
       if (!r.done) done = false;
     } else if (folder === "sent") {
@@ -39128,12 +39162,12 @@ async function syncAll(client2, opts, store) {
         deep: opts.deep ?? false,
         budget
       }, store);
-      synced.sent = r.synced;
+      record2("sent", r.verified, r.synced);
       if (!r.done) done = false;
     } else if (folder === "drafts") {
       const r = await syncDrafts(client2, ids.drafts, store, budget);
-      if (r.done) synced.drafts = r.synced;
-      else {
+      record2("drafts", r.done, r.synced);
+      if (!r.done) {
         draftsUnverified = true;
         done = false;
       }
@@ -39146,11 +39180,182 @@ async function syncAll(client2, opts, store) {
   if (unreadInbox.length > 0) {
     notes.push(`${unreadInbox.length} unread inbox messages cached without bodies. Call ofw_get_message(id) to read them \u2014 this will mark them as read on OFW.`);
   }
+  if (notRefreshed.length > 0) {
+    notes.push(`NOT checked against OurFamilyWizard on this call: ${notRefreshed.join(", ")}. No count is reported for ${notRefreshed.length > 1 ? "those folders" : "that folder"} \u2014 absence of a count means "not looked at", not "no changes". Cached contents may be behind the server; call ofw_sync_messages again to finish, or ofw_check_freshness for a cheap live confirmation.`);
+  }
   if (!done) {
     notes.push("Paused after the request budget to stay within the hosting limit; more pages remain \u2014 call ofw_sync_messages again with the same arguments to resume where it left off and continue the backfill.");
   }
   const note = notes.length > 0 ? notes.join("\n\n") : void 0;
-  return { synced, unreadInbox, done, ...note ? { note } : {} };
+  return {
+    synced,
+    unreadInbox,
+    done,
+    syncComplete: done,
+    refreshed,
+    notRefreshed,
+    ...note ? { note } : {}
+  };
+}
+
+// src/config.ts
+import { createHash } from "node:crypto";
+import { homedir as homedir3 } from "node:os";
+import { join as join4 } from "node:path";
+function readCacheIdentity() {
+  return readEnvVar("OFW_CACHE_IDENTITY") ?? readEnvVar("OFW_USERNAME") ?? "_default";
+}
+function getCacheDir() {
+  const override = process.env.OFW_CACHE_DIR;
+  if (override && override.trim().length > 0) return override.trim();
+  return join4(homedir3(), ".cache", "ofw-mcp");
+}
+function getCacheDbPath() {
+  const identity = readCacheIdentity();
+  const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
+  return join4(getCacheDir(), `${hash2}.db`);
+}
+function getAttachmentsDir() {
+  const override = process.env.OFW_ATTACHMENTS_DIR;
+  if (override && override.trim().length > 0) return override.trim();
+  return join4(homedir3(), "Downloads", "ofw-mcp");
+}
+function getWriteMode() {
+  const raw = process.env.OFW_WRITE_MODE;
+  if (typeof raw !== "string" || raw.trim().length === 0) return "all";
+  const mode = raw.trim().toLowerCase();
+  if (mode === "none" || mode === "drafts" || mode === "all") return mode;
+  console.error(
+    `[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" \u2014 failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`
+  );
+  return "none";
+}
+function getCalendarWritesAllowed() {
+  const mode = getWriteMode();
+  if (mode === "all") return true;
+  return mode === "drafts" && parseBoolEnv("OFW_CALENDAR_WRITES");
+}
+function getDefaultInlineAttachments() {
+  return parseBoolEnv("OFW_INLINE_ATTACHMENTS");
+}
+function getSyncMaxRequests() {
+  const raw = readEnvVar("OFW_SYNC_MAX_REQUESTS");
+  if (raw === void 0) return Number.POSITIVE_INFINITY;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) return Number.POSITIVE_INFINITY;
+  return n;
+}
+var DEFAULT_FRESHNESS_TTL_SECONDS = 300;
+function getFreshnessTtlSeconds() {
+  const raw = readEnvVar("OFW_FRESHNESS_TTL_SECONDS");
+  if (raw === void 0) return DEFAULT_FRESHNESS_TTL_SECONDS;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) return DEFAULT_FRESHNESS_TTL_SECONDS;
+  return n;
+}
+
+// src/tools/freshness.ts
+var RANK = { fresh: 0, unverified: 1, stale: 2 };
+function worst(a, b) {
+  return RANK[a] >= RANK[b] ? a : b;
+}
+function describeAge(seconds) {
+  return seconds < 60 ? `${seconds} sec ago` : `${Math.round(seconds / 60)} min ago`;
+}
+async function buildFreshness(store, opts) {
+  const now = opts.now ?? /* @__PURE__ */ new Date();
+  const ttl = opts.ttlSeconds ?? getFreshnessTtlSeconds();
+  const emptyScope = opts.source === "cache" && opts.folders.length === 0;
+  let staleness = emptyScope ? "stale" : "fresh";
+  let oldestVerifiedAt = null;
+  let sawNeverVerified = false;
+  let lastServerSyncAt = null;
+  let historyComplete = true;
+  let syncComplete = !emptyScope;
+  const deferred = [];
+  const backfilling = [];
+  for (const folder of opts.folders) {
+    const verifiedAt = await getFolderVerifiedAt(store, folder);
+    const state = await store.getSyncState(folder);
+    if (state !== null && (lastServerSyncAt === null || state.lastSyncAt > lastServerSyncAt)) {
+      lastServerSyncAt = state.lastSyncAt;
+    }
+    if (state !== null && state.resumePage !== null) {
+      historyComplete = false;
+      syncComplete = false;
+      backfilling.push(folder);
+    }
+    if (verifiedAt === null) {
+      sawNeverVerified = true;
+      staleness = worst(staleness, "stale");
+      syncComplete = false;
+      continue;
+    }
+    if (oldestVerifiedAt === null || verifiedAt < oldestVerifiedAt) oldestVerifiedAt = verifiedAt;
+    if (state !== null && state.lastSyncAt > verifiedAt) {
+      staleness = worst(staleness, "unverified");
+      syncComplete = false;
+      deferred.push(folder);
+      continue;
+    }
+    const age = Math.max(0, Math.floor((now.getTime() - Date.parse(verifiedAt)) / 1e3));
+    if (age > ttl) staleness = worst(staleness, "unverified");
+  }
+  if (opts.source === "live") {
+    const asOf2 = now.toISOString();
+    const block2 = {
+      source: "live",
+      asOf: asOf2,
+      ageSeconds: 0,
+      staleness: "fresh",
+      lastServerSyncAt,
+      syncComplete,
+      historyComplete
+    };
+    const liveReasons = [];
+    if (sawNeverVerified) {
+      liveReasons.push("the surrounding cache has never been checked against OurFamilyWizard, so anything you did NOT fetch in this call is unverified");
+    }
+    if (backfilling.length > 0) {
+      liveReasons.push(`older history is still being backfilled for ${backfilling.join(", ")}, so older messages may be missing from the cache`);
+    }
+    if (liveReasons.length > 0) {
+      block2.warning = `Fetched live from OurFamilyWizard, so this data is current. Note that ${liveReasons.join("; ")}.`;
+    }
+    return block2;
+  }
+  const asOf = sawNeverVerified ? null : oldestVerifiedAt;
+  const ageSeconds = asOf === null ? null : Math.max(0, Math.floor((now.getTime() - Date.parse(asOf)) / 1e3));
+  const block = {
+    source: "cache",
+    asOf,
+    ageSeconds,
+    staleness,
+    lastServerSyncAt,
+    syncComplete,
+    historyComplete
+  };
+  const reasons = [];
+  if (emptyScope) {
+    reasons.push("this result is backed by no synced folder at all, so nothing about it has been verified");
+  }
+  if (sawNeverVerified) {
+    reasons.push("this data has never been checked against OurFamilyWizard");
+  }
+  if (deferred.length > 0) {
+    reasons.push(`the last sync did not finish checking ${deferred.join(", ")}`);
+  }
+  if (asOf !== null && ageSeconds !== null && ageSeconds > ttl) {
+    reasons.push(`that is past the ${ttl}s freshness threshold`);
+  }
+  if (backfilling.length > 0) {
+    reasons.push(`older history is still being backfilled for ${backfilling.join(", ")}`);
+  }
+  if (reasons.length > 0) {
+    const served = asOf === null ? "Served from cache that was never verified against OurFamilyWizard" : `Served from cache last verified ${describeAge(ageSeconds)}`;
+    block.warning = `${served}; ${reasons.join("; ")}. Re-read before asserting current state \u2014 call ofw_check_freshness for a cheap live confirmation, or ofw_sync_messages to refresh.`;
+  }
+  return block;
 }
 
 // src/tools/draft-freshness.ts
@@ -39203,6 +39408,10 @@ async function fetchServerDraft(client2, id) {
     recipients: mapRecipients(detail.recipients)
   };
 }
+var SUBSTANTIVE_FIELDS = ["subject", "body", "recipients"];
+function substantiveChanges(changed) {
+  return changed.filter((f) => SUBSTANTIVE_FIELDS.includes(f));
+}
 function diffFields(a, b) {
   const changed = [];
   if (a.subject !== b.subject) changed.push("subject");
@@ -39226,6 +39435,17 @@ function checkDraftFreshness(input) {
     if (expectedRevision === actual) {
       return { verdict: "FRESH", reason: "expectedRevision matches the live server draft.", changedFields: [] };
     }
+    if (cached2 !== null && draftRevision(cached2) === expectedRevision) {
+      const changedFields2 = diffFields(server, cached2);
+      if (substantiveChanges(changedFields2).length === 0) {
+        return {
+          verdict: "FRESH",
+          reason: `Only connector-authored metadata (${changedFields2.join(", ")}) changed since you read the draft; its subject, body and recipients are unchanged, so this is not a conflict.`,
+          changedFields: changedFields2,
+          metadataOnly: true
+        };
+      }
+    }
     return {
       verdict: "STALE",
       reason: `expectedRevision ${expectedRevision} does not match the live server draft (${actual}) \u2014 it changed after you read it.`,
@@ -39243,6 +39463,14 @@ function checkDraftFreshness(input) {
   if (changedFields.length === 0) {
     return { verdict: "FRESH", reason: "The cached draft matches the live server draft.", changedFields: [] };
   }
+  if (substantiveChanges(changedFields).length === 0) {
+    return {
+      verdict: "FRESH",
+      reason: `Only connector-authored metadata (${changedFields.join(", ")}) differs from the cached copy; subject, body and recipients match, so this is not a conflict.`,
+      changedFields,
+      metadataOnly: true
+    };
+  }
   return {
     verdict: "STALE",
     reason: `The draft on OurFamilyWizard differs from the cached copy (${changedFields.join(", ")}) \u2014 it was edited outside this tool.`,
@@ -39263,56 +39491,95 @@ function staleDraftPayload(input) {
   };
 }
 
-// src/config.ts
-import { createHash } from "node:crypto";
-import { homedir as homedir3 } from "node:os";
-import { join as join4 } from "node:path";
-function readCacheIdentity() {
-  return readEnvVar("OFW_CACHE_IDENTITY") ?? readEnvVar("OFW_USERNAME") ?? "_default";
-}
-function getCacheDir() {
-  const override = process.env.OFW_CACHE_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join4(homedir3(), ".cache", "ofw-mcp");
-}
-function getCacheDbPath() {
-  const identity = readCacheIdentity();
-  const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
-  return join4(getCacheDir(), `${hash2}.db`);
-}
-function getAttachmentsDir() {
-  const override = process.env.OFW_ATTACHMENTS_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join4(homedir3(), "Downloads", "ofw-mcp");
-}
-function getWriteMode() {
-  const raw = process.env.OFW_WRITE_MODE;
-  if (typeof raw !== "string" || raw.trim().length === 0) return "all";
-  const mode = raw.trim().toLowerCase();
-  if (mode === "none" || mode === "drafts" || mode === "all") return mode;
-  console.error(
-    `[ofw-mcp] Unrecognized OFW_WRITE_MODE "${raw.trim()}" \u2014 failing closed to "none" (no write tools registered). Valid values: none, drafts, all.`
-  );
-  return "none";
-}
-function getCalendarWritesAllowed() {
-  const mode = getWriteMode();
-  if (mode === "all") return true;
-  return mode === "drafts" && parseBoolEnv("OFW_CALENDAR_WRITES");
-}
-function getDefaultInlineAttachments() {
-  return parseBoolEnv("OFW_INLINE_ATTACHMENTS");
+// src/tools/attachments.ts
+import { readFileSync, statSync, mkdirSync, writeFileSync } from "node:fs";
+import { basename, dirname as dirname2, extname } from "node:path";
+var MIME_BY_EXT = {
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".heic": "image/heic",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".csv": "text/csv",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".json": "application/json",
+  ".xml": "application/xml",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".zip": "application/zip",
+  ".ics": "text/calendar"
+};
+function mimeFromName(name) {
+  return MIME_BY_EXT[extname(name).toLowerCase()] ?? "application/octet-stream";
 }
-function getSyncMaxRequests() {
-  const raw = readEnvVar("OFW_SYNC_MAX_REQUESTS");
-  if (raw === void 0) return Number.POSITIVE_INFINITY;
-  const n = Number(raw);
-  if (!Number.isInteger(n) || n <= 0) return Number.POSITIVE_INFINITY;
-  return n;
+var OCTET_STREAM = "application/octet-stream";
+var HOST_RENDERABLE_IMAGE_MIMES = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp"
+]);
+function normalizeMimeType(raw) {
+  if (!raw) return OCTET_STREAM;
+  const bare = raw.split(";", 1)[0].trim().toLowerCase();
+  return bare || OCTET_STREAM;
+}
+var PNG_MAGIC = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+var JPEG_MAGIC = Buffer.from([255, 216, 255]);
+function sniffImageMime(bytes) {
+  if (bytes.length >= 8 && bytes.subarray(0, 8).equals(PNG_MAGIC)) return "image/png";
+  if (bytes.length >= 3 && bytes.subarray(0, 3).equals(JPEG_MAGIC)) return "image/jpeg";
+  if (bytes.length >= 6 && bytes.toString("ascii", 0, 4) === "GIF8") return "image/gif";
+  if (bytes.length >= 12 && bytes.toString("ascii", 0, 4) === "RIFF" && bytes.toString("ascii", 8, 12) === "WEBP") {
+    return "image/webp";
+  }
+  return null;
+}
+function resolveDownloadMime(bytes, headerMime, fileName) {
+  const sniffed = sniffImageMime(bytes);
+  if (sniffed) return sniffed;
+  const fromHeader = normalizeMimeType(headerMime);
+  if (fromHeader !== OCTET_STREAM) return fromHeader;
+  return mimeFromName(fileName);
+}
+function isHostRenderableImage(mime) {
+  return HOST_RENDERABLE_IMAGE_MIMES.has(mime);
 }
+var NodeAttachmentIO = class {
+  supportsDisk = true;
+  async resolveUpload(path) {
+    const abs = expandPath(path);
+    const stat = statSync(abs);
+    if (!stat.isFile()) throw new Error(`Not a file: ${abs}`);
+    const fileName = basename(abs);
+    const mimeType = mimeFromName(fileName);
+    const blob = await fileBlob(abs, { type: mimeType });
+    return { blob, fileName, mimeType, sizeBytes: stat.size };
+  }
+  readDownloaded(path) {
+    try {
+      return readFileSync(path);
+    } catch {
+      return null;
+    }
+  }
+  writeDownload(dest, bytes) {
+    mkdirSync(dirname2(dest), { recursive: true });
+    writeFileSync(dest, bytes);
+  }
+};
 
 // src/tools/messages.ts
-import { basename, join as join5 } from "node:path";
+import { basename as basename2, join as join5 } from "node:path";
 var DateSchema = external_exports.looseObject({ dateTime: external_exports.string() });
 var SentDetailSchema = external_exports.looseObject({
   subject: external_exports.string().optional(),
@@ -39326,7 +39593,9 @@ var SavedDraftDetailSchema = external_exports.looseObject({
   body: external_exports.string().optional(),
   date: DateSchema.optional(),
   replyToId: external_exports.number().nullable().optional(),
-  recipients: external_exports.array(ApiRecipientSchema).optional()
+  recipients: external_exports.array(ApiRecipientSchema).optional(),
+  // Read to audit whether requested myFileIDs actually attached (Defect 3).
+  files: external_exports.array(external_exports.number()).optional()
 });
 var MessageDetailSchema = external_exports.looseObject({
   id: external_exports.number(),
@@ -39342,6 +39611,21 @@ var MessageDetailSchema = external_exports.looseObject({
   folder: external_exports.looseObject({ id: external_exports.number() }).optional()
 });
 var DetailFilesSchema = external_exports.looseObject({ files: external_exports.array(external_exports.number()).optional() });
+var FolderCountsSchema = external_exports.looseObject({
+  systemFolders: external_exports.array(external_exports.looseObject({
+    id: external_exports.string(),
+    folderType: external_exports.string(),
+    totalCount: external_exports.number().optional(),
+    messageCount: external_exports.number().optional(),
+    count: external_exports.number().optional()
+  })).optional()
+});
+var FOLDER_TYPE = {
+  inbox: "INBOX",
+  sent: "SENT_MESSAGES",
+  drafts: "DRAFTS"
+};
+var MAX_FRESHNESS_IDS = 25;
 var UploadedFileSchema = external_exports.looseObject({
   fileId: external_exports.number(),
   fileName: external_exports.string().optional(),
@@ -39357,16 +39641,23 @@ function listDataHintsAtFiles(listData) {
   if (Array.isArray(ld.files)) return ld.files.length > 0;
   return false;
 }
+async function draftsFreshness(cache) {
+  const freshness = await buildFreshness(cache, { source: "cache", folders: ["drafts"] });
+  const completed = await getDraftsCacheStatus(cache);
+  const cacheStatus = completed === "fresh" && freshness.staleness === "fresh" ? "fresh" : "unverified";
+  return { freshness, serverConfirmed: cacheStatus === "fresh", cacheStatus };
+}
 function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
   const writeMode = getWriteMode();
   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 client2.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 \u2014 the cache may have 1000+ messages. Call ofw_sync_messages first if the cache is empty or stale.",
@@ -39390,14 +39681,22 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     else {
       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 \u2014 this empty result says nothing about what is in the cache.'
       });
     }
     const cache = cacheProvider();
     const filter = { folder, since: args.since, until: args.until, q: args.q };
     const total = await cache.countMessages(filter);
     const messages = (await cache.listMessages({ ...filter, page, size })).map((m) => withReadState(m));
-    const payload = { messages, total, page, size };
+    const freshness = await buildFreshness(cache, {
+      source: "cache",
+      folders: folder === void 0 ? ["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.";
     } else if (page * size < total) {
@@ -39416,6 +39715,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     const cache = cacheProvider();
     const draftRow = await cache.getDraft(id);
     if (draftRow !== null) {
+      const { freshness: freshness2, serverConfirmed, cacheStatus } = await draftsFreshness(cache);
       return jsonResponse({
         id: draftRow.id,
         folder: "drafts",
@@ -39435,7 +39735,12 @@ function registerMessageTools(server, client2, 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: freshness2
       });
     }
     const cached2 = await cache.getMessage(id);
@@ -39473,7 +39778,8 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
         } catch {
         }
       }
-      return jsonResponse({ ...withReadState(row2), attachments: attachments2 });
+      const freshness2 = await buildFreshness(cache, { source: "cache", folders: [row2.folder] });
+      return jsonResponse({ ...withReadState(row2), attachments: attachments2, freshness: freshness2 });
     }
     const detail = parseLenient(
       MessageDetailSchema,
@@ -39505,7 +39811,8 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       await fetchAttachmentMetaForMessage(client2, detail.id, detail.files, cache);
     }
     const attachments = await cache.listAttachmentsForMessage(detail.id);
-    return jsonResponse({ ...withReadState(row), attachments });
+    const freshness = await buildFreshness(cache, { source: "live", folders: [folder] });
+    return jsonResponse({ ...withReadState(row), attachments, freshness });
   });
   if (allowSend) server.registerTool("ofw_send_message", {
     description: "Send a message via OurFamilyWizard. To send an existing draft, pass messageId \u2014 subject/body/recipientIds become optional overrides (missing fields default to the draft's cached values) and the draft is deleted after sending. To send a fresh message, supply subject/body/recipientIds directly. draftId is the legacy spelling of messageId and works the same way. If replyToId is provided, the cache may rewrite it to the latest reply in the same thread (a note is included in the response when this happens). Attach files by passing their fileIds (from ofw_upload_attachment) in myFileIDs. After sending, the tool re-fetches the message from OFW to populate the local cache and link attachments to the new message id.",
@@ -39653,7 +39960,10 @@ ${text}` : text);
       };
     }
     const verdict = checkDraftFreshness({ server: server2, cached: cached2, expectedRevision });
-    if (verdict.verdict === "FRESH") return { ok: true, note: null };
+    if (verdict.verdict === "FRESH") {
+      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) {
       console.error(`[ofw-mcp] WARNING: force:true overrode a ${verdict.verdict} verdict on draft ${draftId} (${action}). ${verdict.reason}`);
       const echoed = server2 === null ? "The draft no longer existed on OurFamilyWizard." : `The server version that was overwritten is preserved below under "overwrittenServerDraft".`;
@@ -39690,20 +40000,30 @@ ${JSON.stringify(
     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 });
-    const drafts = rows.map((d) => ({ ...d, revision: draftRevision(d), cacheStatus }));
+    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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 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 \u2014 merge your edit into it and retry with expectedRevision.",
     annotations: { readOnlyHint: false },
     inputSchema: {
       subject: external_exports.string().describe("Message subject"),
@@ -39758,32 +40078,67 @@ ${JSON.stringify(
     let replaceNote = null;
     let verifyNote = null;
     let newRevision = null;
+    const warnings = [];
     if (newId !== null) {
       verifyNote = verifyWriteLanded("draft", { subject: args.subject, body: args.body }, detail);
+      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 ?? (/* @__PURE__ */ new Date()).toISOString(),
         listData: detail
       };
       await cache.upsertDraft(persisted);
       newRevision = draftRevision(persisted);
+      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} \u2014 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.`
+        );
+      }
+      if (args.recipientIds !== void 0 && 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.`
+          );
+        }
+      }
       if (args.messageId !== void 0 && args.messageId !== newId) {
         try {
           await deleteOFWMessages(client2, [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) {
           replaceNote = `WARNING: New draft ${newId} was created successfully, but the old draft ${args.messageId} could NOT be deleted: ${e.message}. BOTH drafts now exist on OurFamilyWizard and nothing was lost. Verify ${newId} reads correctly, then remove ${args.messageId} with ofw_delete_draft.`;
         }
       }
     }
-    const responseObj = persisted !== null ? { ...persisted, revision: newRevision, cacheStatus: "fresh" } : raw;
+    const responseObj = persisted !== null ? {
+      ...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}
 
 ${text}` : text);
@@ -39823,9 +40178,15 @@ ${text}` : text);
   }, 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 });
+    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) {
@@ -39835,9 +40196,13 @@ ${text}` : text);
       }
     }
     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", {
     description: `Upload a local file to OurFamilyWizard's "My Files" so it can be attached to a message. Returns the fileId \u2014 pass that to ofw_send_message or ofw_save_draft in myFileIDs to attach it. The file is uploaded as PRIVATE (visible only to you) by default; pass shareClass:"SHARED" to share with co-parents directly via the My Files area.`,
@@ -39881,18 +40246,20 @@ ${text}` : text);
     });
   });
   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 \u2014 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 \u2014 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: external_exports.number().describe("Attachment file id (from ofw_get_message \u2192 attachments[].fileId)"),
-      inline: external_exports.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: external_exports.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: external_exports.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 \u2014 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: external_exports.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: external_exports.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();
+    const inline = requestedInline || !attachmentIO.supportsDisk;
+    const forcedInline = inline && !requestedInline;
     let cached2 = await cache.getAttachment(fileId);
     if (!cached2) {
       await fetchAttachmentMeta(client2, fileId, 0, cache);
@@ -39901,36 +40268,39 @@ ${text}` : text);
     }
     if (inline) {
       let bytes = null;
-      let mimeType = cached2.mimeType;
-      let fileName = cached2.fileName;
+      let headerMime = cached2.mimeType;
+      let fileName2 = cached2.fileName;
       if (cached2.downloadedPath) {
         bytes = attachmentIO.readDownloaded(cached2.downloadedPath);
       }
       if (bytes === null) {
         const response2 = await client2.requestBinary("GET", `/pub/v1/myfiles/${fileId}/data`);
         bytes = response2.body;
-        mimeType = response2.contentType ?? cached2.mimeType;
-        fileName = response2.suggestedFileName ?? cached2.fileName;
+        headerMime = response2.contentType ?? cached2.mimeType;
+        fileName2 = response2.suggestedFileName ?? cached2.fileName;
       }
+      const mimeType = resolveDownloadMime(bytes, headerMime, fileName2);
       const base643 = bytes.toString("base64");
-      const metaBlock = { type: "text", text: JSON.stringify({
+      const meta3 = {
         fileId,
-        fileName,
+        fileName: fileName2,
         mimeType,
         sizeBytes: bytes.length,
         mode: "inline"
-      }, null, 2) };
-      if (mimeType.startsWith("image/")) {
+      };
+      if (forcedInline) meta3.forcedInline = true;
+      const metaBlock = { type: "text", text: JSON.stringify(meta3, null, 2) };
+      if (isHostRenderableImage(mimeType)) {
         return { content: [metaBlock, { type: "image", data: base643, mimeType }] };
       }
       return { content: [metaBlock, { type: "resource", resource: {
-        uri: `ofw://attachment/${fileId}/${encodeURIComponent(fileName)}`,
+        uri: `ofw://attachment/${fileId}/${encodeURIComponent(fileName2)}`,
         mimeType,
         blob: base643
       } }] };
     }
     let dest;
-    const safeName = basename(cached2.fileName);
+    const safeName = basename2(cached2.fileName);
     if (args.saveTo) {
       const isDirArg = args.saveTo.endsWith("/") || args.saveTo.endsWith("\\");
       const abs = expandPath2(args.saveTo);
@@ -39940,9 +40310,12 @@ ${text}` : text);
     }
     if (!args.force && cached2.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: cached2.mimeType,
+        mimeType: resolveDownloadMime(Buffer.alloc(0), cached2.mimeType, cached2.fileName),
         sizeBytes: cached2.sizeBytes,
         fileName: cached2.fileName,
         note: "already downloaded"
@@ -39951,31 +40324,137 @@ ${text}` : text);
     const response = await client2.requestBinary("GET", `/pub/v1/myfiles/${fileId}/data`);
     attachmentIO.writeDownload(dest, response.body);
     await cache.markAttachmentDownloaded(fileId, dest);
+    const fileName = response.suggestedFileName ?? cached2.fileName;
     return jsonResponse({
       fileId,
       path: dest,
-      mimeType: response.contentType ?? cached2.mimeType,
+      mimeType: resolveDownloadMime(response.body, response.contentType ?? cached2.mimeType, fileName),
       sizeBytes: response.body.length,
-      fileName: response.suggestedFileName ?? cached2.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 \u2014 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: external_exports.array(external_exports.enum(["inbox", "sent", "drafts"])).describe("Folders to sync (default: all three)").optional(),
+      folders: external_exports.array(external_exports.enum(["inbox", "sent", "drafts"])).min(1).describe("Folders to sync (default: all three). Must be non-empty if given \u2014 an empty list would sync nothing while reporting success.").optional(),
       fetchUnreadBodies: external_exports.boolean().describe("If true, also fetch bodies for unread inbox messages (will mark them as read on OFW). Default false.").optional(),
       deep: external_exports.boolean().describe("If true, walk every OFW page until empty regardless of cache state. Use to backfill gaps. Default false.").optional(),
       maxRequests: external_exports.number().int().min(1).describe("Maximum OFW requests this single call may make before pausing. When hit, the response reports done:false \u2014 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(client2, {
       folders: args.folders,
       fetchUnreadBodies: args.fetchUnreadBodies,
       deep: args.deep,
       maxRequests: args.maxRequests ?? getSyncMaxRequests()
-    }, cacheProvider());
-    return jsonResponse(result);
+    }, cache);
+    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 \u2014 especially "draft X is still sitting unsent" \u2014 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: external_exports.array(external_exports.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: external_exports.array(external_exports.number()).describe(`Specific ids to verify against OFW (max ${MAX_FRESHNESS_IDS}). By default only ids present in the drafts cache are probed \u2014 see allowMarkRead.`).optional(),
+      allowMarkRead: external_exports.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 \u2014 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);
+    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 client2.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;
+        const inSync = serverCount === null || !historyComplete ? null : serverCount === cachedCount;
+        folders.push({
+          folder,
+          existsOnServer: entry !== void 0,
+          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);
+      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 server2 = await fetchServerDraft(client2, id);
+        const cacheRevision = cachedDraft === null ? null : draftRevision(cachedDraft);
+        if (server2 === 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 \u2014 it was sent or deleted elsewhere. Do not describe it as still unsent."
+          });
+          continue;
+        }
+        const serverRevision = draftRevision(server2);
+        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 \u2014 it was edited on OurFamilyWizard since the last sync. Run ofw_sync_messages before reading or writing it." } : {}
+        });
+      } catch (e) {
+        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: (/* @__PURE__ */ 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 \u2014 call again with the rest.`;
+    }
+    return jsonResponse(payload);
   });
 }
 async function deleteOFWMessages(client2, ids) {
@@ -40210,8 +40689,8 @@ function registerJournalTools(server, client2) {
 
 // src/cache/node.ts
 import { DatabaseSync } from "node:sqlite";
-import { mkdirSync, chmodSync, existsSync } from "node:fs";
-import { dirname as dirname2 } from "node:path";
+import { mkdirSync as mkdirSync2, chmodSync, existsSync } from "node:fs";
+import { dirname as dirname3 } from "node:path";
 
 // src/cache/store.ts
 function rowFromDb(r) {
@@ -40705,7 +41184,7 @@ var NodeSqlDriver = class {
   }
 };
 function enforceCachePermissions(dbPath) {
-  chmodSync(dirname2(dbPath), 448);
+  chmodSync(dirname3(dbPath), 448);
   chmodSync(dbPath, 384);
   for (const sibling of [`${dbPath}-wal`, `${dbPath}-shm`]) {
     if (existsSync(sibling)) chmodSync(sibling, 384);
@@ -40719,7 +41198,7 @@ var OFWCache = class _OFWCache extends LocalCacheStore {
   db;
   static open(path) {
     const memory = path === ":memory:";
-    if (!memory) mkdirSync(dirname2(path), { recursive: true });
+    if (!memory) mkdirSync2(dirname3(path), { recursive: true });
     const db = new DatabaseSync(path);
     if (!memory) enforceCachePermissions(path);
     db.exec("PRAGMA journal_mode = WAL");
@@ -40733,59 +41212,6 @@ var OFWCache = class _OFWCache extends LocalCacheStore {
   }
 };
 
-// src/tools/attachments.ts
-import { readFileSync, statSync, mkdirSync as mkdirSync2, writeFileSync } from "node:fs";
-import { basename as basename2, dirname as dirname3, extname } from "node:path";
-var MIME_BY_EXT = {
-  ".pdf": "application/pdf",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".heic": "image/heic",
-  ".txt": "text/plain",
-  ".md": "text/markdown",
-  ".csv": "text/csv",
-  ".html": "text/html",
-  ".htm": "text/html",
-  ".json": "application/json",
-  ".xml": "application/xml",
-  ".doc": "application/msword",
-  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-  ".xls": "application/vnd.ms-excel",
-  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-  ".ppt": "application/vnd.ms-powerpoint",
-  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-  ".zip": "application/zip",
-  ".ics": "text/calendar"
-};
-function mimeFromName(name) {
-  return MIME_BY_EXT[extname(name).toLowerCase()] ?? "application/octet-stream";
-}
-var NodeAttachmentIO = class {
-  async resolveUpload(path) {
-    const abs = expandPath(path);
-    const stat = statSync(abs);
-    if (!stat.isFile()) throw new Error(`Not a file: ${abs}`);
-    const fileName = basename2(abs);
-    const mimeType = mimeFromName(fileName);
-    const blob = await fileBlob(abs, { type: mimeType });
-    return { blob, fileName, mimeType, sizeBytes: stat.size };
-  }
-  readDownloaded(path) {
-    try {
-      return readFileSync(path);
-    } catch {
-      return null;
-    }
-  }
-  writeDownload(dest, bytes) {
-    mkdirSync2(dirname3(dest), { recursive: true });
-    writeFileSync(dest, bytes);
-  }
-};
-
 // src/index.ts
 var originalEmit = process.emit.bind(process);
 process.emit = function(event, ...args) {
@@ -40802,7 +41228,7 @@ var nodeCacheProvider = () => nodeCache ??= OFWCache.open(getCacheDbPath());
 var nodeAttachmentIO = new NodeAttachmentIO();
 await runMcp({
   name: "ofw",
-  version: "2.6.7",
+  version: "2.7.1",
   // x-release-please-version
   deps: client,
   tools: [