ofw-mcp 2.7.1 → 2.9.0

package/dist/bundle.js

@@ -13672,9 +13672,9 @@ var ZodSet = class _ZodSet extends ZodType {
       }
     }
     const valueType = this._def.valueType;
-    function finalizeSet(elements2) {
+    function finalizeSet(elements3) {
       const parsedSet = /* @__PURE__ */ new Set();
-      for (const element of elements2) {
+      for (const element of elements3) {
         if (element.status === "aborted")
           return INVALID;
         if (element.status === "dirty")
@@ -13683,11 +13683,11 @@ var ZodSet = class _ZodSet extends ZodType {
       }
       return { status: status.value, value: parsedSet };
     }
-    const elements = [...ctx.data.values()].map((item, i) => valueType._parse(new ParseInputLazyPath(ctx, item, ctx.path, i)));
+    const elements2 = [...ctx.data.values()].map((item, i) => valueType._parse(new ParseInputLazyPath(ctx, item, ctx.path, i)));
     if (ctx.common.async) {
-      return Promise.all(elements).then((elements2) => finalizeSet(elements2));
+      return Promise.all(elements2).then((elements3) => finalizeSet(elements3));
     } else {
-      return finalizeSet(elements);
+      return finalizeSet(elements2);
     }
   }
   min(minSize, message) {
@@ -38407,7 +38407,7 @@ async function loginWithPassword(username, password) {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.7.1",
+  version: "2.9.0",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -38856,6 +38856,7 @@ async function resolveFolderIds(client2, store) {
   };
   await store.setMeta("drafts_folder_id", ids.drafts);
   await store.setMeta("sent_folder_id", ids.sent);
+  await store.setMeta("inbox_folder_id", ids.inbox);
   return ids;
 }
 var ListItemSchema = external_exports.looseObject({
@@ -38972,7 +38973,7 @@ async function walkPages(client2, folder, folderId, opts, store) {
         await fetchAttachmentMetaBudgeted(client2, item.id, detailFileIds, store, budget);
       }
     }
-    await store.upsertMessages(toUpsert);
+    if (toUpsert.length > 0) await store.upsertMessages(toUpsert);
     if (pageBudgetHit) {
       return { synced, unread, newestId, pagesFetched, done: false, nextPage: page };
     }
@@ -39235,6 +39236,23 @@ function getCalendarWritesAllowed() {
   if (mode === "all") return true;
   return mode === "drafts" && parseBoolEnv("OFW_CALENDAR_WRITES");
 }
+function getAllowMarkRead() {
+  const raw = process.env.OFW_ALLOW_MARK_READ;
+  if (typeof raw !== "string" || raw.trim().length === 0) return true;
+  const value = raw.trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(value)) return true;
+  if (["0", "false", "no", "off"].includes(value)) return false;
+  console.error(
+    `[ofw-mcp] Unrecognized OFW_ALLOW_MARK_READ "${raw.trim()}" \u2014 failing closed to "false" (no tool may mark a message read on OFW). Valid values: true, false.`
+  );
+  return false;
+}
+function getFetchUnreadBodies() {
+  return parseBoolEnv("OFW_FETCH_UNREAD_BODIES");
+}
+function getAutoRefreshStaleReads() {
+  return parseBoolEnv("OFW_AUTO_REFRESH");
+}
 function getDefaultInlineAttachments() {
   return parseBoolEnv("OFW_INLINE_ATTACHMENTS");
 }
@@ -39380,12 +39398,30 @@ var ServerDraftSchema = external_exports.looseObject({
   subject: external_exports.string().optional(),
   body: external_exports.string().optional(),
   replyToId: external_exports.number().nullable().optional(),
-  recipients: external_exports.array(ApiRecipientSchema).optional()
+  recipients: external_exports.array(ApiRecipientSchema).optional(),
+  // Read for the LIFECYCLE answer (see tools/lifecycle.ts): which folder OFW
+  // itself says this id lives in right now. `existsOnServer` alone cannot
+  // distinguish "still a draft" from "was sent" — a sent draft still exists.
+  // `id` accepts BOTH spellings deliberately. This schema is parsed in
+  // `mode: 'strict'` because it backs the destructive-draft guard, so a
+  // present-but-mistyped field THROWS — and OFW is already inconsistent about
+  // this exact field: the folders listing (`FoldersSchema` in sync.ts) types it
+  // `z.string()`, while message detail has been observed returning a number.
+  // Pinning one spelling here would turn a harmless representation change into
+  // a hard failure of ofw_save_draft / ofw_delete_draft, which is the opposite
+  // of what a strict boundary is for: it exists to stop us acting on a response
+  // we cannot interpret, not to reject one we can. `folderId` is normalized to
+  // a string below, so both spellings compare correctly downstream.
+  folder: external_exports.looseObject({
+    id: external_exports.union([external_exports.string(), external_exports.number()]).optional(),
+    name: external_exports.string().optional()
+  }).nullable().optional(),
+  date: external_exports.looseObject({ dateTime: external_exports.string().optional() }).nullable().optional()
 });
 function isNotFound(e) {
   return e instanceof Error && /OFW API error: 404\b/.test(e.message);
 }
-async function fetchServerDraft(client2, id) {
+async function fetchMessageSnapshot(client2, id) {
   let raw;
   try {
     raw = await client2.request("GET", `/pub/v3/messages/${id}`);
@@ -39402,12 +39438,20 @@ async function fetchServerDraft(client2, id) {
     mode: "strict"
   });
   return {
-    subject: detail.subject ?? "",
-    body: detail.body ?? "",
-    replyToId: detail.replyToId ?? null,
-    recipients: mapRecipients(detail.recipients)
+    content: {
+      subject: detail.subject ?? "",
+      body: detail.body ?? "",
+      replyToId: detail.replyToId ?? null,
+      recipients: mapRecipients(detail.recipients)
+    },
+    folderId: detail.folder?.id === void 0 ? null : String(detail.folder.id),
+    folderName: detail.folder?.name ?? null,
+    dateTime: detail.date?.dateTime ?? null
   };
 }
+async function fetchServerDraft(client2, id) {
+  return (await fetchMessageSnapshot(client2, id))?.content ?? null;
+}
 var SUBSTANTIVE_FIELDS = ["subject", "body", "recipients"];
 function substantiveChanges(changed) {
   return changed.filter((f) => SUBSTANTIVE_FIELDS.includes(f));
@@ -39491,6 +39535,1037 @@ function staleDraftPayload(input) {
   };
 }
 
+// src/tools/lifecycle.ts
+var FOLDER_TYPE = {
+  inbox: "INBOX",
+  sent: "SENT_MESSAGES",
+  drafts: "DRAFTS"
+};
+var FOLDER_ID_META_KEY = {
+  inbox: "inbox_folder_id",
+  sent: "sent_folder_id",
+  drafts: "drafts_folder_id"
+};
+var FOLDERS = ["inbox", "sent", "drafts"];
+async function readFolderIdMap(store) {
+  return {
+    inbox: await store.getMeta(FOLDER_ID_META_KEY.inbox),
+    sent: await store.getMeta(FOLDER_ID_META_KEY.sent),
+    drafts: await store.getMeta(FOLDER_ID_META_KEY.drafts)
+  };
+}
+async function persistFolderIds(store, systemFolders) {
+  for (const folder of FOLDERS) {
+    const entry = systemFolders.find((f) => f.folderType === FOLDER_TYPE[folder]);
+    if (entry !== void 0) await store.setMeta(FOLDER_ID_META_KEY[folder], entry.id);
+  }
+}
+async function ensureFolderIdMap(client2, store) {
+  const cached2 = await readFolderIdMap(store);
+  if (cached2.inbox !== null && cached2.sent !== null && cached2.drafts !== null) {
+    return { map: cached2, requests: 0 };
+  }
+  try {
+    const ids = await resolveFolderIds(client2, store);
+    return { map: { inbox: ids.inbox, sent: ids.sent, drafts: ids.drafts }, requests: 1 };
+  } catch {
+    return { map: cached2, requests: 1 };
+  }
+}
+function classifyState(snapshot, map2) {
+  if (snapshot === null) return "deleted";
+  const { folderId } = snapshot;
+  if (folderId === null) return "unknown";
+  if (map2.drafts !== null && folderId === map2.drafts) return "draft";
+  if (map2.sent !== null && folderId === map2.sent) return "sent";
+  if (map2.inbox !== null && folderId === map2.inbox) return "received";
+  return "unknown";
+}
+function probeWouldStamp(cachedDraft, cachedMessage) {
+  if (cachedDraft !== null) return false;
+  if (cachedMessage === null) return true;
+  if (cachedMessage.folder === "sent") return false;
+  return !deriveRead(cachedMessage);
+}
+var SKIP_NOTE = 'Verifying this id requires fetching its detail from OurFamilyWizard, which would mark an unread inbox message as READ and stamp a co-parent-visible "First Viewed" time on the record. Ids already cached as drafts, as sent, or as already-read inbox messages are probed freely because none of those can stamp anything. Run ofw_sync_messages (it walks list pages, not bodies) or pass allowMarkRead:true.';
+function stateNote(state, cachedAsDraft, folderName) {
+  if (state === "deleted") {
+    return cachedAsDraft ? "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." : "Not found on OurFamilyWizard.";
+  }
+  if (state === "sent") {
+    return cachedAsDraft ? "This id is cached as a DRAFT but OurFamilyWizard now has it in Sent \u2014 it was SENT (see sentAt). It is no longer a draft; saying it is still unsent would be false." : "This id is a sent message on OurFamilyWizard.";
+  }
+  if (state === "received") {
+    return cachedAsDraft ? "This id is cached as a draft but OurFamilyWizard has it in the Inbox. Run ofw_sync_messages to reconcile." : "This id is an inbox message on OurFamilyWizard.";
+  }
+  if (state === "unknown") {
+    return `OurFamilyWizard did not report a folder this tool can map${folderName === null ? "" : ` (it reported "${folderName}")`}, so what this id has become is NOT established. Treat it as unverified rather than assuming it is unchanged.`;
+  }
+  return void 0;
+}
+async function probeIds(client2, store, ids, opts) {
+  const draftsById = new Map((await store.getDrafts(ids)).map((d) => [d.id, d]));
+  const messagesById = new Map((await store.getMessages(ids)).map((m) => [m.id, m]));
+  const prepared = ids.map((id) => {
+    const cachedDraft = draftsById.get(id) ?? null;
+    const cachedMessage = cachedDraft === null ? messagesById.get(id) ?? null : null;
+    return {
+      id,
+      cachedDraft,
+      cachedMessage,
+      skip: !opts.allowMarkRead && probeWouldStamp(cachedDraft, cachedMessage)
+    };
+  });
+  let requests = 0;
+  let map2 = { inbox: null, sent: null, drafts: null };
+  if (prepared.some((p) => !p.skip)) {
+    const resolved = await ensureFolderIdMap(client2, store);
+    map2 = resolved.map;
+    requests += resolved.requests;
+  }
+  const keyById = new Map(
+    (await store.getDraftLineageByIds(ids)).map((l) => [l.id, l.draftKey])
+  );
+  const items = [];
+  for (const p of prepared) {
+    if (p.skip) {
+      items.push({ id: p.id, skipped: true, reason: "WOULD_MARK_READ", note: SKIP_NOTE });
+      continue;
+    }
+    const probe = await probeOne(client2, p, map2, keyById.get(p.id) ?? null);
+    requests += probe.requests;
+    items.push(probe.item);
+  }
+  return { items, requests };
+}
+async function probeOne(client2, prepared, map2, draftKey) {
+  const { id, cachedDraft } = prepared;
+  let snapshot;
+  try {
+    snapshot = await fetchMessageSnapshot(client2, id);
+  } catch (e) {
+    return {
+      requests: 1,
+      item: {
+        id,
+        error: "FRESHNESS_CHECK_FAILED",
+        message: e.message,
+        inSync: null,
+        note: "The freshness check itself failed, so nothing is confirmed either way."
+      }
+    };
+  }
+  const state = classifyState(snapshot, map2);
+  const cacheRevision = cachedDraft === null ? null : draftRevision(cachedDraft);
+  const serverRevision = snapshot === null ? null : draftRevision(snapshot.content);
+  const viewedAt = snapshot?.content.recipients.find((r) => r.viewedAt !== null)?.viewedAt ?? null;
+  let inSync;
+  if (cachedDraft === null) inSync = null;
+  else if (snapshot === null) inSync = false;
+  else if (cacheRevision !== serverRevision) inSync = false;
+  else if (state === "draft") inSync = true;
+  else if (state === "unknown") inSync = null;
+  else inSync = false;
+  const notes = [];
+  const stateN = stateNote(state, cachedDraft !== null, snapshot?.folderName ?? null);
+  if (stateN !== void 0) notes.push(stateN);
+  if (snapshot !== null && cachedDraft === null) {
+    notes.push("Not in the drafts cache, so there is no cached copy to compare its content against (inSync is null, not false).");
+  } else if (snapshot !== null && cacheRevision !== serverRevision) {
+    notes.push("Content differs from the cache \u2014 it was edited on OurFamilyWizard since the last sync. Run ofw_sync_messages before reading or writing it.");
+  }
+  return {
+    requests: 1,
+    item: {
+      id,
+      state,
+      folder: snapshot?.folderName ?? null,
+      sentAt: state === "sent" ? snapshot?.dateTime ?? null : null,
+      viewedAt,
+      existsOnServer: snapshot !== null,
+      cacheRevision,
+      serverRevision,
+      inSync,
+      ...draftKey !== null ? { draftKey } : {},
+      ...notes.length > 0 ? { note: notes.join(" ") } : {}
+    }
+  };
+}
+async function resolveDraftKey(store, draftKey) {
+  const chain = await store.getDraftLineage(draftKey);
+  if (chain.length === 0) return null;
+  return { currentId: chain[chain.length - 1].id, ids: chain.map((r) => r.id) };
+}
+function newDraftKey() {
+  return `dk_${crypto.randomUUID()}`;
+}
+
+// src/extract/inflate.ts
+var MAX_DECOMPRESSED_BYTES = 32 * 1024 * 1024;
+var DecompressionLimitError = class extends Error {
+  constructor(label, limit) {
+    super(`${label} expands past the ${limit}-byte decompression cap`);
+    this.name = "DecompressionLimitError";
+  }
+};
+async function inflateBounded(data, format, limit, label) {
+  const stream = new Blob([data]).stream().pipeThrough(new DecompressionStream(format));
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > limit) {
+      await reader.cancel();
+      throw new DecompressionLimitError(label, limit);
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks);
+}
+
+// src/extract/zip.ts
+var EOCD_SIG = 101010256;
+var CENTRAL_SIG = 33639248;
+var LOCAL_SIG = 67324752;
+var ZIP64_SENTINEL = 4294967295;
+var ZIP_MAX_UNCOMPRESSED_BYTES = MAX_DECOMPRESSED_BYTES;
+function findEocd(bytes) {
+  const earliest = Math.max(0, bytes.length - (22 + 65535));
+  for (let i = bytes.length - 22; i >= earliest; i--) {
+    if (bytes.readUInt32LE(i) === EOCD_SIG) return i;
+  }
+  throw new Error("not a ZIP archive (no end-of-central-directory record)");
+}
+async function readZip(bytes, opts = {}) {
+  const limit = opts.maxUncompressedBytes ?? ZIP_MAX_UNCOMPRESSED_BYTES;
+  const eocd = findEocd(bytes);
+  const count = bytes.readUInt16LE(eocd + 10);
+  const cdOffset = bytes.readUInt32LE(eocd + 16);
+  if (cdOffset === ZIP64_SENTINEL || count === 65535) {
+    throw new Error("ZIP64 archives are not supported");
+  }
+  const entries = /* @__PURE__ */ new Map();
+  let p = cdOffset;
+  for (let i = 0; i < count; i++) {
+    if (bytes.readUInt32LE(p) !== CENTRAL_SIG) {
+      throw new Error(`corrupt ZIP central directory at offset ${p}`);
+    }
+    const nameLen = bytes.readUInt16LE(p + 28);
+    const extraLen = bytes.readUInt16LE(p + 30);
+    const commentLen = bytes.readUInt16LE(p + 32);
+    const name = bytes.toString("utf8", p + 46, p + 46 + nameLen);
+    entries.set(name, {
+      name,
+      method: bytes.readUInt16LE(p + 10),
+      compressedSize: bytes.readUInt32LE(p + 20),
+      uncompressedSize: bytes.readUInt32LE(p + 24),
+      localOffset: bytes.readUInt32LE(p + 42)
+    });
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+  const cache = /* @__PURE__ */ new Map();
+  async function read(name) {
+    const cached2 = cache.get(name);
+    if (cached2) return cached2;
+    const entry = entries.get(name);
+    if (!entry) return null;
+    if (entry.uncompressedSize > limit) {
+      throw new Error(
+        `ZIP member ${name} is too large to extract (${entry.uncompressedSize} bytes)`
+      );
+    }
+    const lo = entry.localOffset;
+    if (bytes.readUInt32LE(lo) !== LOCAL_SIG) {
+      throw new Error(`corrupt ZIP local header for ${name}`);
+    }
+    const start = lo + 30 + bytes.readUInt16LE(lo + 26) + bytes.readUInt16LE(lo + 28);
+    const raw = bytes.subarray(start, start + entry.compressedSize);
+    let out;
+    if (entry.method === 0) out = Buffer.from(raw);
+    else if (entry.method === 8) out = await inflateBounded(raw, "deflate-raw", limit, `ZIP member ${name}`);
+    else throw new Error(`unsupported ZIP compression method ${entry.method} for ${name}`);
+    cache.set(name, out);
+    return out;
+  }
+  return {
+    names: () => [...entries.keys()],
+    has: (name) => entries.has(name),
+    read,
+    async readText(name) {
+      const buf = await read(name);
+      if (!buf) return null;
+      const text = buf.toString("utf8");
+      return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+    }
+  };
+}
+
+// src/extract/xml.ts
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'"
+};
+function decodeXmlEntities(text) {
+  if (!text.includes("&")) return text;
+  return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (whole, body) => {
+    if (body[0] === "#") {
+      const code = body[1] === "x" || body[1] === "X" ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      return String.fromCodePoint(code);
+    }
+    return NAMED_ENTITIES[body] ?? whole;
+  });
+}
+function* elements(xml, tag) {
+  const re = new RegExp(`<${tag}((?:\\s[^>]*?)?)(?:\\s*/>|>([\\s\\S]*?)</${tag}>)`, "g");
+  for (let m = re.exec(xml); m !== null; m = re.exec(xml)) {
+    yield { attrs: m[1], inner: m[2] ?? "" };
+  }
+}
+function attr(attrs, name) {
+  const m = new RegExp(`(?:^|\\s)${name}\\s*=\\s*("([^"]*)"|'([^']*)')`).exec(attrs);
+  if (!m) return null;
+  return decodeXmlEntities(m[2] ?? m[3]);
+}
+function textOf(xml, tag) {
+  let out = "";
+  for (const el of elements(xml, tag)) out += decodeXmlEntities(el.inner);
+  return out;
+}
+
+// src/extract/ooxml.ts
+function resolvePartPath(baseDir, target) {
+  if (target.startsWith("/")) return target.slice(1);
+  const segments = (baseDir + target).split("/");
+  const out = [];
+  for (const segment of segments) {
+    if (segment === "." || segment === "") continue;
+    if (segment === "..") out.pop();
+    else out.push(segment);
+  }
+  return out.join("/");
+}
+function dirOf(partPath) {
+  const i = partPath.lastIndexOf("/");
+  return i === -1 ? "" : partPath.slice(0, i + 1);
+}
+async function readRels(zip, partPath) {
+  const dir = dirOf(partPath);
+  const base = partPath.slice(dir.length);
+  const xml = await zip.readText(`${dir}_rels/${base}.rels`);
+  if (!xml) return [];
+  const rels = [];
+  for (const el of elements(xml, "Relationship")) {
+    const id = attr(el.attrs, "Id");
+    const target = attr(el.attrs, "Target");
+    if (!id || !target) continue;
+    rels.push({ id, target: resolvePartPath(dir, target), type: attr(el.attrs, "Type") ?? "" });
+  }
+  return rels;
+}
+function findPart(zip, conventional, fileName) {
+  if (zip.has(conventional)) return conventional;
+  return zip.names().find((n) => n.endsWith(`/${fileName}`) || n === fileName) ?? null;
+}
+
+// src/extract/spreadsheet.ts
+var DEFAULT_MAX_CELLS = 2e5;
+var BUILTIN_DATE_FORMATS = /* @__PURE__ */ new Set([14, 15, 16, 17, 18, 19, 20, 21, 22, 45, 46, 47]);
+var SERIAL_EPOCH_OFFSET = 25569;
+function excelSerialToIso(serial, date1904) {
+  const base = date1904 ? serial + 1462 : serial;
+  const corrected = Math.floor(base) < 60 ? base + 1 : base;
+  const date5 = new Date(Math.round((corrected - SERIAL_EPOCH_OFFSET) * 864e5));
+  if (Number.isNaN(date5.getTime())) return null;
+  const iso = date5.toISOString();
+  if (base < 1) return iso.slice(11, 19);
+  return iso.slice(11, 19) === "00:00:00" ? iso.slice(0, 10) : iso.slice(0, 19);
+}
+function isDateFormat(numFmtId, formatCode) {
+  if (BUILTIN_DATE_FORMATS.has(numFmtId)) return true;
+  if (!formatCode) return false;
+  const bare = formatCode.replace(/"[^"]*"/g, "").replace(/\[[^\]]*\]/g, "").replace(/\\./g, "");
+  return /[ymdhs]/i.test(bare);
+}
+function columnIndex(ref) {
+  const m = /^([A-Z]+)/.exec(ref);
+  if (!m) return null;
+  let index = 0;
+  for (const ch of m[1]) index = index * 26 + (ch.charCodeAt(0) - 64);
+  return index - 1;
+}
+function csvField(value) {
+  return /[",\r\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+function toCsv(rows, cols) {
+  return rows.map((row) => Array.from({ length: cols }, (_, i) => csvField(row[i] ?? "")).join(",")).join("\n");
+}
+async function readStyles(zip, dir) {
+  const xml = await zip.readText(`${dir}styles.xml`);
+  if (!xml) return { dateStyles: [] };
+  const custom2 = /* @__PURE__ */ new Map();
+  for (const el of elements(xml, "numFmt")) {
+    const id = Number(attr(el.attrs, "numFmtId"));
+    const code = attr(el.attrs, "formatCode");
+    if (Number.isFinite(id) && code !== null) custom2.set(id, code);
+  }
+  const dateStyles = [];
+  for (const block of elements(xml, "cellXfs")) {
+    for (const xf of elements(block.inner, "xf")) {
+      const id = Number(attr(xf.attrs, "numFmtId") ?? "0");
+      dateStyles.push(isDateFormat(id, custom2.get(id)));
+    }
+  }
+  return { dateStyles };
+}
+async function readSharedStrings(zip, dir) {
+  const xml = await zip.readText(`${dir}sharedStrings.xml`);
+  if (!xml) return [];
+  return [...elements(xml, "si")].map((si) => textOf(si.inner, "t"));
+}
+function cellValue(attrs, inner, ctx) {
+  const type = attr(attrs, "t") ?? "n";
+  if (type === "inlineStr") return textOf(inner, "t");
+  const raw = textOf(inner, "v");
+  switch (type) {
+    case "s": {
+      const index = Number(raw);
+      return ctx.shared[index] ?? "";
+    }
+    case "b":
+      return raw === "1" ? "TRUE" : "FALSE";
+    case "str":
+    case "e":
+      return raw;
+    default: {
+      const styleIndex = Number(attr(attrs, "s") ?? "-1");
+      const numeric = Number(raw);
+      if (ctx.styles.dateStyles[styleIndex] && raw !== "" && Number.isFinite(numeric)) {
+        return excelSerialToIso(numeric, ctx.date1904) ?? raw;
+      }
+      return raw;
+    }
+  }
+}
+function parseSheet(xml, name, ctx, maxCells) {
+  const rows = [];
+  let cols = 0;
+  let cells = 0;
+  let truncated = false;
+  for (const row of elements(xml, "row")) {
+    if (cells >= maxCells) {
+      truncated = true;
+      break;
+    }
+    const values = [];
+    for (const cell of elements(row.inner, "c")) {
+      const ref = attr(cell.attrs, "r");
+      const index = ref === null ? null : columnIndex(ref);
+      if (index === null) continue;
+      values[index] = cellValue(cell.attrs, cell.inner, ctx);
+      cells++;
+      if (index + 1 > cols) cols = index + 1;
+    }
+    rows.push(values);
+  }
+  return { name, rows: rows.length, cols, csv: toCsv(rows, cols), ...truncated ? { truncated } : {} };
+}
+async function extractXlsx(bytes, opts = {}) {
+  const zip = await readZip(bytes);
+  const workbookPath = findPart(zip, "xl/workbook.xml", "workbook.xml");
+  if (!workbookPath) throw new Error("no workbook part found in the .xlsx archive");
+  const dir = dirOf(workbookPath);
+  const workbookXml = await zip.readText(workbookPath) ?? "";
+  const rels = await readRels(zip, workbookPath);
+  const targetById = new Map(rels.map((r) => [r.id, r.target]));
+  const ctx = {
+    shared: await readSharedStrings(zip, dir),
+    styles: await readStyles(zip, dir),
+    date1904: /<workbookPr[^>]*date1904="(1|true)"/i.test(workbookXml)
+  };
+  const maxCells = opts.maxCells ?? DEFAULT_MAX_CELLS;
+  const sheets = [];
+  const omitted = [];
+  let index = 0;
+  for (const el of elements(workbookXml, "sheet")) {
+    const position = index++;
+    const name = attr(el.attrs, "name") ?? `Sheet${position + 1}`;
+    if (opts.select && !opts.select(position, name)) {
+      omitted.push(name);
+      continue;
+    }
+    const relId = attr(el.attrs, "r:id") ?? attr(el.attrs, "id");
+    const path = (relId && targetById.get(relId)) ?? resolvePartPath(dir, `worksheets/sheet${position + 1}.xml`);
+    const xml = await zip.readText(path);
+    if (xml === null) {
+      omitted.push(`${name} (sheet part not found in the workbook)`);
+      continue;
+    }
+    sheets.push(parseSheet(xml, name, ctx, maxCells));
+  }
+  const truncated = sheets.some((s) => s.truncated);
+  return {
+    kind: "spreadsheet",
+    sheets,
+    ...omitted.length ? { omitted } : {},
+    ...truncated ? { truncated } : {}
+  };
+}
+function parseDelimitedRows(text, delimiter) {
+  const rows = [];
+  let row = [];
+  let field = "";
+  let quoted = false;
+  let dirty = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quoted) {
+      if (ch !== '"') {
+        field += ch;
+        continue;
+      }
+      if (text[i + 1] === '"') {
+        field += '"';
+        i++;
+        continue;
+      }
+      quoted = false;
+      continue;
+    }
+    if (ch === '"') {
+      quoted = true;
+      dirty = true;
+      continue;
+    }
+    if (ch === delimiter) {
+      row.push(field);
+      field = "";
+      dirty = true;
+      continue;
+    }
+    if (ch === "\r") continue;
+    if (ch === "\n") {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+      dirty = false;
+      continue;
+    }
+    field += ch;
+    dirty = true;
+  }
+  if (dirty || field !== "") {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+}
+function extractDelimited(text, name, delimiter) {
+  const rows = parseDelimitedRows(text, delimiter);
+  const cols = rows.reduce((max, r) => Math.max(max, r.length), 0);
+  return {
+    kind: "spreadsheet",
+    sheets: [{ name, rows: rows.length, cols, csv: toCsv(rows, cols) }]
+  };
+}
+
+// src/extract/document.ts
+var RUN_CONTENT = /<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t>|<w:(tab|br|cr)\s*\/>/g;
+function paragraphText(inner) {
+  let text = "";
+  for (let m = RUN_CONTENT.exec(inner); m !== null; m = RUN_CONTENT.exec(inner)) {
+    if (m[1] !== void 0) text += decodeXmlEntities(m[1]);
+    else text += m[2] === "tab" ? "	" : "\n";
+  }
+  RUN_CONTENT.lastIndex = 0;
+  return text;
+}
+function styledParagraph(inner) {
+  const text = paragraphText(inner);
+  if (text === "") return "";
+  const style = /<w:pStyle\s[^>]*w:val="([^"]*)"/.exec(inner)?.[1] ?? "";
+  const heading = /^Heading(\d)$/.exec(style);
+  if (heading) return `${"#".repeat(Math.min(Number(heading[1]), 6))} ${text}`;
+  if (style === "Title" || style === "Subtitle") return `# ${text}`;
+  if (style === "ListParagraph") return `- ${text}`;
+  return text;
+}
+function tableText(inner) {
+  const rows = [];
+  for (const tr of elements(inner, "w:tr")) {
+    const cells = [];
+    for (const tc of elements(tr.inner, "w:tc")) {
+      const parts = [];
+      for (const p of elements(tc.inner, "w:p")) {
+        const text = paragraphText(p.inner);
+        if (text !== "") parts.push(text);
+      }
+      cells.push(parts.join(" "));
+    }
+    rows.push(`| ${cells.join(" | ")} |`);
+  }
+  return rows.join("\n");
+}
+var BLOCK = /<w:tbl(?:\s[^>]*?)?>[\s\S]*?<\/w:tbl>|<w:p(?:\s[^>]*?)?(?:\s*\/>|>([\s\S]*?)<\/w:p>)/g;
+async function extractDocx(bytes) {
+  const zip = await readZip(bytes);
+  const path = findPart(zip, "word/document.xml", "document.xml");
+  if (!path) throw new Error("no document part found in the .docx archive");
+  const xml = await zip.readText(path) ?? "";
+  const blocks = [];
+  for (let m = BLOCK.exec(xml); m !== null; m = BLOCK.exec(xml)) {
+    const text = m[0].startsWith("<w:tbl") ? tableText(m[0]) : styledParagraph(m[1] ?? "");
+    if (text !== "") blocks.push(text);
+  }
+  BLOCK.lastIndex = 0;
+  return { kind: "document", text: blocks.join("\n\n") };
+}
+
+// src/extract/presentation.ts
+var SLIDE_PATH = /^ppt\/slides\/slide(\d+)\.xml$/;
+function slideText(xml) {
+  const lines = [];
+  for (const p of elements(xml, "a:p")) {
+    let line = "";
+    for (const t of elements(p.inner, "a:t")) line += decodeXmlEntities(t.inner);
+    if (line !== "") lines.push(line);
+  }
+  return lines.join("\n");
+}
+async function extractPptx(bytes, opts = {}) {
+  const zip = await readZip(bytes);
+  const paths = zip.names().map((name) => ({ name, n: Number(SLIDE_PATH.exec(name)?.[1]) })).filter((e) => Number.isFinite(e.n)).sort((a, b) => a.n - b.n);
+  if (paths.length === 0) throw new Error("no slides found in the .pptx archive");
+  const slides = [];
+  const omitted = [];
+  for (let i = 0; i < paths.length; i++) {
+    const { name } = paths[i];
+    const number4 = i + 1;
+    if (opts.select && !opts.select(i, `slide ${number4}`)) {
+      omitted.push(`slide ${number4}`);
+      continue;
+    }
+    const text = slideText(await zip.readText(name) ?? "");
+    const notesRel = (await readRels(zip, name)).find((r) => r.type.endsWith("/notesSlide"));
+    const notesXml = notesRel ? await zip.readText(notesRel.target) : null;
+    const notes = notesXml === null ? "" : slideText(notesXml);
+    slides.push({ number: number4, text, ...notes ? { notes } : {} });
+  }
+  return {
+    kind: "presentation",
+    slides,
+    ...omitted.length ? { omitted } : {}
+  };
+}
+
+// src/extract/pdf.ts
+var OBJ_HEADER = /(\d+)\s+\d+\s+obj\b/g;
+function parseObjects(text) {
+  const objects = /* @__PURE__ */ new Map();
+  for (let m = OBJ_HEADER.exec(text); m !== null; m = OBJ_HEADER.exec(text)) {
+    const start = m.index + m[0].length;
+    const end = text.indexOf("endobj", start);
+    objects.set(Number(m[1]), {
+      num: Number(m[1]),
+      body: text.slice(start, end === -1 ? void 0 : end),
+      start
+    });
+  }
+  OBJ_HEADER.lastIndex = 0;
+  return objects;
+}
+function refsIn(fragment) {
+  return [...fragment.matchAll(/(\d+)\s+\d+\s+R\b/g)].map((m) => Number(m[1]));
+}
+function orderedPages(objects) {
+  const isPage = (o) => /\/Type\s*\/Page[^s]/.test(o.body);
+  const inFileOrder = [...objects.values()].filter(isPage).sort((a, b) => a.start - b.start);
+  const catalog = [...objects.values()].find((o) => /\/Type\s*\/Catalog/.test(o.body));
+  const rootRef = catalog ? refsIn(/\/Pages\s+[^/>]*/.exec(catalog.body)?.[0] ?? "")[0] : void 0;
+  if (rootRef === void 0) return inFileOrder;
+  const ordered = [];
+  const seen = /* @__PURE__ */ new Set();
+  const walk = (num) => {
+    if (seen.has(num)) return;
+    seen.add(num);
+    const obj = objects.get(num);
+    if (!obj) return;
+    if (isPage(obj)) {
+      ordered.push(obj);
+      return;
+    }
+    const kids = /\/Kids\s*\[([^\]]*)\]/.exec(obj.body)?.[1];
+    if (kids) for (const kid of refsIn(kids)) walk(kid);
+  };
+  walk(rootRef);
+  return ordered.length > 0 ? ordered : inFileOrder;
+}
+function streamBytes(bytes, obj) {
+  const marker = /stream\r?\n/.exec(obj.body);
+  if (!marker) return null;
+  const from = obj.start + marker.index + marker[0].length;
+  const declared = /\/Length\s+(\d+)(?!\s+\d+\s+R)/.exec(obj.body);
+  if (declared) return bytes.subarray(from, from + Number(declared[1]));
+  const end = bytes.indexOf("endstream", from, "latin1");
+  return bytes.subarray(from, end === -1 ? void 0 : end);
+}
+async function decodeStream(bytes, obj) {
+  const raw = streamBytes(bytes, obj);
+  if (!raw) return null;
+  const filter = /\/Filter\s*(\/\w+|\[[^\]]*\])/.exec(obj.body)?.[1] ?? "";
+  if (filter === "") return raw;
+  if (!filter.includes("FlateDecode")) return null;
+  try {
+    return await inflateBounded(raw, "deflate", MAX_DECOMPRESSED_BYTES, "PDF stream");
+  } catch (err) {
+    if (err instanceof DecompressionLimitError) throw err;
+    return null;
+  }
+}
+function readLiteral(text, i) {
+  let value = "";
+  let depth = 1;
+  let p = i + 1;
+  for (; p < text.length; p++) {
+    const ch = text[p];
+    if (ch === "\\") {
+      const esc2 = text[++p];
+      const simple = { n: "\n", r: "\r", t: "	", b: "\b", f: "\f" };
+      if (simple[esc2]) {
+        value += simple[esc2];
+        continue;
+      }
+      const octal = /^[0-7]{1,3}/.exec(text.slice(p, p + 3))?.[0];
+      if (octal) {
+        value += String.fromCharCode(parseInt(octal, 8));
+        p += octal.length - 1;
+        continue;
+      }
+      if (esc2 === "\n") continue;
+      value += esc2;
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      value += ch;
+      continue;
+    }
+    if (ch === ")") {
+      depth--;
+      if (depth === 0) break;
+      value += ch;
+      continue;
+    }
+    value += ch;
+  }
+  return { value, next: p };
+}
+function decodeHexString(hex3) {
+  const clean = hex3.replace(/[^0-9a-fA-F]/g, "");
+  const padded = clean.length % 2 === 1 ? `${clean}0` : clean;
+  const buf = Buffer.from(padded, "hex");
+  if (buf.length >= 2 && buf.length % 2 === 0 && buf[0] === 254 && buf[1] === 255) {
+    return buf.subarray(2).swap16().toString("utf16le");
+  }
+  if (buf.length % 2 === 0 && buf.length > 0 && buf.every((b, i) => i % 2 === 1 || b === 0)) {
+    return buf.swap16().toString("utf16le");
+  }
+  return buf.toString("latin1");
+}
+function textFromContentStream(content) {
+  let out = "";
+  let pending = "";
+  let arrayDepth = 0;
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i];
+    if (ch === "(") {
+      const { value, next } = readLiteral(content, i);
+      pending += value;
+      i = next;
+      continue;
+    }
+    if (ch === "<" && content[i + 1] === "<") {
+      i++;
+      continue;
+    }
+    if (ch === "<") {
+      const end = content.indexOf(">", i);
+      if (end === -1) break;
+      pending += decodeHexString(content.slice(i + 1, end));
+      i = end;
+      continue;
+    }
+    if (ch === "[") {
+      arrayDepth++;
+      continue;
+    }
+    if (ch === "]") {
+      arrayDepth = 0;
+      continue;
+    }
+    if (arrayDepth > 0 && (ch === "-" || ch >= "0" && ch <= "9")) {
+      const num = /^-?\d+(\.\d+)?/.exec(content.slice(i));
+      if (!num) continue;
+      if (Number(num[0]) <= -100) pending += " ";
+      i += num[0].length - 1;
+      continue;
+    }
+    if (/[A-Za-z'"*]/.test(ch)) {
+      const op = /^[A-Za-z*]+|^['"]/.exec(content.slice(i))?.[0] ?? ch;
+      i += op.length - 1;
+      if (op === "Tj" || op === "TJ") {
+        out += pending;
+        pending = "";
+        continue;
+      }
+      if (op === "'" || op === '"') {
+        out += `
+${pending}`;
+        pending = "";
+        continue;
+      }
+      if (op === "Td" || op === "TD" || op === "T*" || op === "ET") {
+        out += "\n";
+        continue;
+      }
+    }
+  }
+  return out;
+}
+function tidy(text) {
+  return text.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+async function extractPdf(bytes, opts = {}) {
+  const text = bytes.toString("latin1");
+  if (/\/Encrypt\b/.test(text)) {
+    throw new Error("the PDF is encrypted; its text cannot be extracted");
+  }
+  const objects = parseObjects(text);
+  const pageObjects = orderedPages(objects);
+  if (pageObjects.length === 0) throw new Error("no pages found in the PDF");
+  const pages = [];
+  const omitted = [];
+  for (let i = 0; i < pageObjects.length; i++) {
+    const number4 = i + 1;
+    if (opts.select && !opts.select(i, `page ${number4}`)) {
+      omitted.push(`page ${number4}`);
+      continue;
+    }
+    const contentsFragment = /\/Contents\s*(\d+\s+\d+\s+R|\[[^\]]*\])/.exec(pageObjects[i].body)?.[1] ?? "";
+    let raw = "";
+    for (const ref of refsIn(contentsFragment)) {
+      const streamObj = objects.get(ref);
+      if (!streamObj) continue;
+      const decoded = await decodeStream(bytes, streamObj);
+      if (decoded) raw += `${decoded.toString("latin1")}
+`;
+    }
+    pages.push({ number: number4, text: tidy(textFromContentStream(raw)) });
+  }
+  const textLayer = pages.some((p) => p.text !== "");
+  return {
+    kind: "pdf",
+    pages,
+    textLayer,
+    ...textLayer ? {} : {
+      note: "This PDF has no extractable text layer \u2014 it is most likely a scan or an image-only export. Reading it requires OCR, which this server does not perform."
+    },
+    ...omitted.length ? { omitted } : {}
+  };
+}
+
+// src/extract/index.ts
+var MIME_KINDS = {
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+  "application/vnd.ms-excel.sheet.macroenabled.12": "xlsx",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+  "application/pdf": "pdf",
+  "text/csv": "csv",
+  "text/tab-separated-values": "tsv",
+  "application/json": "text",
+  "application/xml": "text",
+  "application/xhtml+xml": "text",
+  "application/javascript": "text",
+  "application/x-yaml": "text"
+};
+var EXT_KINDS = {
+  ".xlsx": "xlsx",
+  ".xlsm": "xlsx",
+  ".docx": "docx",
+  ".pptx": "pptx",
+  ".pdf": "pdf",
+  ".csv": "csv",
+  ".tsv": "tsv",
+  ".tab": "tsv",
+  ".txt": "text",
+  ".md": "text",
+  ".json": "text",
+  ".xml": "text",
+  ".html": "text",
+  ".htm": "text",
+  ".log": "text",
+  ".yaml": "text",
+  ".yml": "text",
+  ".ics": "text",
+  ".vcf": "text",
+  ".srt": "text"
+};
+function extractKindFor(mimeType, fileName) {
+  const byMime = MIME_KINDS[mimeType];
+  if (byMime) return byMime;
+  const dot = fileName.lastIndexOf(".");
+  const byExt = dot === -1 ? void 0 : EXT_KINDS[fileName.slice(dot).toLowerCase()];
+  if (byExt) return byExt;
+  return mimeType.startsWith("text/") ? "text" : null;
+}
+function parsePartSpec(spec) {
+  const ranges = [];
+  const names = /* @__PURE__ */ new Set();
+  for (const token of spec.split(",").map((t) => t.trim()).filter(Boolean)) {
+    const range = /^(\d+)\s*-\s*(\d+)$/.exec(token);
+    if (range) {
+      ranges.push([Number(range[1]), Number(range[2])]);
+      continue;
+    }
+    if (/^\d+$/.test(token)) ranges.push([Number(token), Number(token)]);
+    names.add(token.toLowerCase());
+  }
+  if (ranges.length === 0 && names.size === 0) return () => true;
+  return (index, name) => ranges.some(([from, to]) => index + 1 >= from && index + 1 <= to) || names.has(name.toLowerCase());
+}
+function clip(text, budget) {
+  const cut = text.slice(0, budget);
+  const lastBreak = cut.lastIndexOf("\n");
+  return lastBreak > 0 ? cut.slice(0, lastBreak) : cut;
+}
+function omissionNote(label) {
+  return `${label} (omitted: response character budget)`;
+}
+function applyCharBudget(extracted, maxChars) {
+  switch (extracted.kind) {
+    case "text":
+    case "document": {
+      if (extracted.text.length <= maxChars) return extracted;
+      return { ...extracted, text: clip(extracted.text, maxChars), truncated: true };
+    }
+    case "spreadsheet": {
+      const sheets = [];
+      const omitted = [...extracted.omitted ?? []];
+      let budget = maxChars;
+      let truncated = extracted.truncated ?? false;
+      for (const sheet of extracted.sheets) {
+        if (budget <= 0) {
+          omitted.push(omissionNote(sheet.name));
+          truncated = true;
+          continue;
+        }
+        if (sheet.csv.length <= budget) {
+          sheets.push(sheet);
+          budget -= sheet.csv.length;
+          continue;
+        }
+        const csv = clip(sheet.csv, budget);
+        sheets.push({ ...sheet, csv, rows: csv.split("\n").length, truncated: true });
+        budget = 0;
+        truncated = true;
+      }
+      return {
+        ...extracted,
+        sheets,
+        truncated,
+        ...omitted.length ? { omitted } : {}
+      };
+    }
+    case "presentation": {
+      const slides = [];
+      const omitted = [...extracted.omitted ?? []];
+      let budget = maxChars;
+      let truncated = extracted.truncated ?? false;
+      for (const slide of extracted.slides) {
+        const size = slide.text.length + (slide.notes?.length ?? 0);
+        if (budget <= 0) {
+          omitted.push(omissionNote(`slide ${slide.number}`));
+          truncated = true;
+          continue;
+        }
+        if (size <= budget) {
+          slides.push(slide);
+          budget -= size;
+          continue;
+        }
+        slides.push({ ...slide, text: clip(slide.text, budget), notes: void 0 });
+        budget = 0;
+        truncated = true;
+      }
+      return { ...extracted, slides, truncated, ...omitted.length ? { omitted } : {} };
+    }
+    case "pdf": {
+      const pages = [];
+      const omitted = [...extracted.omitted ?? []];
+      let budget = maxChars;
+      let truncated = extracted.truncated ?? false;
+      for (const page of extracted.pages) {
+        if (budget <= 0) {
+          omitted.push(omissionNote(`page ${page.number}`));
+          truncated = true;
+          continue;
+        }
+        if (page.text.length <= budget) {
+          pages.push(page);
+          budget -= page.text.length;
+          continue;
+        }
+        pages.push({ ...page, text: clip(page.text, budget) });
+        budget = 0;
+        truncated = true;
+      }
+      return { ...extracted, pages, truncated, ...omitted.length ? { omitted } : {} };
+    }
+  }
+}
+var DEFAULT_MAX_CHARS = 5e4;
+function decodeText(bytes) {
+  const text = bytes.toString("utf8");
+  return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
+}
+async function extractAttachment(bytes, mimeType, fileName, opts = {}) {
+  const kind = extractKindFor(mimeType, fileName);
+  if (kind === null) return null;
+  const select = opts.parts === void 0 ? void 0 : parsePartSpec(opts.parts);
+  let extracted;
+  switch (kind) {
+    case "xlsx":
+      extracted = await extractXlsx(bytes, { select });
+      break;
+    case "csv":
+      extracted = extractDelimited(decodeText(bytes), fileName, ",");
+      break;
+    case "tsv":
+      extracted = extractDelimited(decodeText(bytes), fileName, "	");
+      break;
+    case "docx":
+      extracted = await extractDocx(bytes);
+      break;
+    case "pptx":
+      extracted = await extractPptx(bytes, { select });
+      break;
+    case "pdf":
+      extracted = await extractPdf(bytes, { select });
+      break;
+    case "text":
+      extracted = { kind: "text", text: decodeText(bytes) };
+      break;
+  }
+  return applyCharBudget(extracted, opts.maxChars ?? DEFAULT_MAX_CHARS);
+}
+
 // src/tools/attachments.ts
 import { readFileSync, statSync, mkdirSync, writeFileSync } from "node:fs";
 import { basename, dirname as dirname2, extname } from "node:path";
@@ -39578,6 +40653,65 @@ var NodeAttachmentIO = class {
   }
 };
 
+// src/tools/delivery.ts
+async function tryExtract(bytes, mimeType, fileName, opts) {
+  try {
+    const extracted = await extractAttachment(bytes, mimeType, fileName, {
+      maxChars: opts.maxChars,
+      parts: opts.parts
+    });
+    if (!extracted) {
+      return { reason: `no text extractor for ${mimeType} (${fileName})` };
+    }
+    return { extracted, truncated: extracted.truncated ?? false };
+  } catch (err) {
+    return { reason: `extraction failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+async function buildInlineDelivery(input) {
+  const { fileId, fileName, mimeType, bytes, forcedInline, options } = input;
+  const meta3 = {
+    fileId,
+    fileName,
+    mimeType,
+    sizeBytes: bytes.length,
+    mode: "inline"
+  };
+  if (forcedInline) meta3.forcedInline = true;
+  const block = () => ({ type: "text", text: JSON.stringify(meta3, null, 2) });
+  if (isHostRenderableImage(mimeType)) {
+    meta3.deliveredVia = "image";
+    return { content: [block(), { type: "image", data: bytes.toString("base64"), mimeType }] };
+  }
+  const attempts = [];
+  if (options.extract === false) {
+    attempts.push("extraction skipped (extract:false)");
+  } else {
+    const outcome = await tryExtract(bytes, mimeType, fileName, options);
+    if (outcome.extracted) {
+      meta3.deliveredVia = "extracted";
+      meta3.extracted = outcome.extracted;
+      meta3.truncated = outcome.truncated;
+      meta3.note = "Content extracted from the file. Pass extract:false to get the raw bytes instead.";
+      return { content: [block()] };
+    }
+    attempts.push(outcome.reason ?? "extraction produced no content");
+  }
+  meta3.deliveredVia = "blob";
+  meta3.deliveryAttempts = attempts;
+  meta3.note = "Returned as raw bytes. Some hosts cannot render an embedded resource of this type; if it came back unreadable, the file has no text extractor here (see deliveryAttempts).";
+  return {
+    content: [block(), {
+      type: "resource",
+      resource: {
+        uri: `ofw://attachment/${fileId}/${encodeURIComponent(fileName)}`,
+        mimeType,
+        blob: bytes.toString("base64")
+      }
+    }]
+  };
+}
+
 // src/tools/messages.ts
 import { basename as basename2, join as join5 } from "node:path";
 var DateSchema = external_exports.looseObject({ dateTime: external_exports.string() });
@@ -39608,7 +40742,10 @@ var MessageDetailSchema = external_exports.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: external_exports.looseObject({ id: external_exports.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: external_exports.looseObject({ id: external_exports.union([external_exports.string(), external_exports.number()]) }).optional()
 });
 var DetailFilesSchema = external_exports.looseObject({ files: external_exports.array(external_exports.number()).optional() });
 var FolderCountsSchema = external_exports.looseObject({
@@ -39620,11 +40757,6 @@ var FolderCountsSchema = external_exports.looseObject({
     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(),
@@ -39647,6 +40779,51 @@ async function draftsFreshness(cache) {
   const cacheStatus = completed === "fresh" && freshness.staleness === "fresh" ? "fresh" : "unverified";
   return { freshness, serverConfirmed: cacheStatus === "fresh", cacheStatus };
 }
+var 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.';
+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) };
+}
+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}" \u2014 ${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
+  });
+}
+function markReadVerdict(cached2, requested) {
+  const ceiling = getAllowMarkRead();
+  if (ceiling && (requested ?? true)) return null;
+  const wouldStamp = cached2 === null || cached2.folder === "inbox" && !deriveRead(cached2);
+  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: cached2?.id ?? null,
+    reason: cached2 === 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 \u2014 it cannot be undone. To read it anyway, call again with allowMarkRead:true${ceiling ? "" : " (which this deployment does not permit \u2014 clear OFW_ALLOW_MARK_READ to re-enable)"}.`,
+    ...cached2 === 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: cached2.subject, fromUser: cached2.fromUser, sentAt: cached2.sentAt }
+  });
+}
 function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
   const writeMode = getWriteMode();
   const allowSend = writeMode === "all";
@@ -39660,15 +40837,16 @@ function registerMessageTools(server, client2, 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 \u2014 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 \u2014 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" \u2014 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: external_exports.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
       page: external_exports.number().int().min(1).describe("Page number (default 1)").optional(),
       size: external_exports.number().int().min(1).describe("Messages per page (default 50)").optional(),
       since: external_exports.string().describe("ISO date or datetime \u2014 only messages with sent_at >= since (inclusive)").optional(),
       until: external_exports.string().describe("ISO date or datetime \u2014 only messages with sent_at < until (exclusive)").optional(),
-      q: external_exports.string().describe("Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.").optional()
+      q: external_exports.string().describe("Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.").optional(),
+      autoRefresh: external_exports.boolean().describe(AUTO_REFRESH_DESC).optional()
     }
   }, async (args) => {
     const page = args.page ?? 1;
@@ -39679,36 +40857,66 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     else if (folderArg === "sent") folder = "sent";
     else if (folderArg === "both") folder = void 0;
     else {
-      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 \u2014 this empty result says nothing about what is in the cache.'
+      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 \u2014 do not read it as "no messages".'
       });
     }
     const cache = cacheProvider();
+    const folders = folder === void 0 ? ["inbox", "sent"] : [folder];
     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 freshness = await buildFreshness(cache, {
-      source: "cache",
-      folders: folder === void 0 ? ["inbox", "sent"] : [folder]
+    const { value, refreshed, unverifiedEmpty } = await guardedCacheRead({
+      client: client2,
+      cache,
+      folders,
+      autoRefresh: args.autoRefresh ?? getAutoRefreshStaleReads(),
+      isEmpty: (v) => v.total === 0,
+      read: async () => {
+        const total2 = await cache.countMessages(filter);
+        const messages2 = (await cache.listMessages({ ...filter, page, size })).map((m) => withReadState(m));
+        const freshness2 = await buildFreshness(cache, { source: "cache", folders });
+        return { messages: messages2, total: total2, freshness: freshness2 };
+      }
     });
-    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;
+    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 \u2014 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}\u2013${(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) \u2014 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 \u2014 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) \u2014 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: external_exports.string().describe("Message ID (also accepts draft IDs \u2014 drafts are routed via the drafts cache)")
+      messageId: external_exports.string().describe("Message ID (also accepts draft IDs \u2014 drafts are routed via the drafts cache)"),
+      allowMarkRead: external_exports.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 \u2014 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);
@@ -39735,6 +40943,11 @@ 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),
+        // 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
@@ -39781,6 +40994,8 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       const freshness2 = await buildFreshness(cache, { source: "cache", folders: [row2.folder] });
       return jsonResponse({ ...withReadState(row2), attachments: attachments2, freshness: freshness2 });
     }
+    const markReadCheck = markReadVerdict(cached2, args.allowMarkRead);
+    if (markReadCheck !== null) return markReadCheck;
     const detail = parseLenient(
       MessageDetailSchema,
       await client2.request("GET", `/pub/v3/messages/${encodeURIComponent(args.messageId)}`),
@@ -39888,6 +41103,7 @@ function registerMessageTools(server, client2, 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 = {
@@ -39904,6 +41120,16 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
         listData: detail
       };
       await cache.upsertMessage(persisted);
+      if (draftRef !== void 0) {
+        const prior = await cache.getDraftLineageById(draftRef);
+        const now = (/* @__PURE__ */ 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;
+      }
       for (const fileId of myFileIDs) {
         const existing = await cache.getAttachment(fileId);
         await cache.upsertAttachmentForMessage({
@@ -39925,7 +41151,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       await deleteOFWMessages(client2, [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}
@@ -39990,35 +41216,65 @@ ${JSON.stringify(
     };
   }
   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" \u2014 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: external_exports.number().int().min(1).describe("Page number (default 1)").optional(),
-      size: external_exports.number().int().min(1).describe("Drafts per page (default 50)").optional()
+      size: external_exports.number().int().min(1).describe("Drafts per page (default 50)").optional(),
+      autoRefresh: external_exports.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 });
-    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 \u2014 call ofw_sync_messages to populate, or ofw_check_freshness to confirm."
+    const { value, refreshed, unverifiedEmpty } = await guardedCacheRead({
+      client: client2,
+      cache,
+      folders: ["drafts"],
+      autoRefresh: args.autoRefresh ?? getAutoRefreshStaleReads(),
+      isEmpty: (v) => v.total === 0,
+      read: async () => {
+        const { freshness: freshness2, serverConfirmed: serverConfirmed2, cacheStatus } = await draftsFreshness(cache);
+        const rows = await cache.listDrafts({ page, size });
+        const total2 = await cache.countDrafts();
+        const keyById = new Map(
+          (await cache.getDraftLineageByIds(rows.map((d) => d.id))).map((l) => [l.id, l.draftKey])
+        );
+        const drafts2 = rows.map((d) => ({
+          ...d,
+          revision: draftRevision(d),
+          draftKey: keyById.get(d.id) ?? null,
+          cacheStatus,
+          serverConfirmed: serverConfirmed2,
+          asOf: freshness2.asOf
+        }));
+        return { drafts: drafts2, total: total2, freshness: freshness2, serverConfirmed: serverConfirmed2 };
+      }
+    });
+    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;
+    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 \u2014 call ofw_status(includeDraftInventory:true) for a live, complete one.");
+    }
     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.';
+      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, 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 \u2014 ofw_save_draft and ofw_delete_draft re-check the server and refuse a stale overwrite.';
+    }
+    if (refreshed) {
+      payload.autoRefreshed = true;
     }
     return jsonResponse(payload);
   });
@@ -40078,6 +41334,7 @@ ${JSON.stringify(
     let replaceNote = null;
     let verifyNote = null;
     let newRevision = null;
+    let draftKey = null;
     const warnings = [];
     if (newId !== null) {
       verifyNote = verifyWriteLanded("draft", { subject: args.subject, body: args.body }, detail);
@@ -40094,10 +41351,34 @@ ${JSON.stringify(
       };
       await cache.upsertDraft(persisted);
       newRevision = draftRevision(persisted);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      if (args.messageId !== void 0) {
+        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
+      });
       if (resolvedReplyTo !== null && effectiveReplyTo !== resolvedReplyTo) {
         const rewrittenFrom = requestedReplyTo !== resolvedReplyTo ? ` (rewritten from ${requestedReplyTo})` : "";
+        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 \u2014 to that message, not the one requested \u2014 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} \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.`
+          `replyToId was requested as ${resolvedReplyTo}${rewrittenFrom} but the saved draft came back with replyToId ${effectiveReplyTo === null ? "null" : effectiveReplyTo} \u2014 ${outcome} If threading matters, verify on ourfamilywizard.com.`
         );
       }
       if (args.recipientIds !== void 0 && Array.isArray(detail.recipients)) {
@@ -40132,6 +41413,11 @@ ${JSON.stringify(
       ...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 } : {}
@@ -40169,25 +41455,46 @@ ${text}` : text);
 ${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: external_exports.number().int().min(1).describe("Page (default 1)").optional(),
-      size: external_exports.number().int().min(1).describe("Per page (default 50)").optional()
+      size: external_exports.number().int().min(1).describe("Per page (default 50)").optional(),
+      autoRefresh: external_exports.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 });
-    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: client2,
+      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 sent2 = await cache.listMessages({ folder: "sent", page, size });
+        const total2 = await cache.countMessages({ folder: "sent" });
+        const freshness2 = await buildFreshness(cache, { source: "cache", folders: ["sent"] });
+        return { sent: sent2, total: total2, freshness: freshness2 };
+      }
+    });
+    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);
@@ -40195,14 +41502,17 @@ ${text}` : text);
         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 \u2014 or not read \u2014 a message since without the cache hearing about it.";
+    }
+    if (refreshed) {
+      payload.autoRefreshed = true;
     }
-    return jsonResponse({ unread, freshness });
+    return jsonResponse(payload);
   });
   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.`,
@@ -40246,13 +41556,16 @@ ${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 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 \u2014 per-sheet CSV, per-page/slide text, document text \u2014 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 \u2014 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: 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 (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(),
+      inline: external_exports.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 \u2014 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: 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()
+      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(),
+      extract: external_exports.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: external_exports.number().int().min(500).max(5e5).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: external_exports.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;
@@ -40260,6 +41573,7 @@ ${text}` : text);
     const requestedInline = args.inline ?? getDefaultInlineAttachments();
     const inline = requestedInline || !attachmentIO.supportsDisk;
     const forcedInline = inline && !requestedInline;
+    const deliveryOptions = { extract: args.extract, maxChars: args.maxChars, parts: args.parts };
     let cached2 = await cache.getAttachment(fileId);
     if (!cached2) {
       await fetchAttachmentMeta(client2, fileId, 0, cache);
@@ -40279,25 +41593,15 @@ ${text}` : text);
         headerMime = response2.contentType ?? cached2.mimeType;
         fileName2 = response2.suggestedFileName ?? cached2.fileName;
       }
-      const mimeType = resolveDownloadMime(bytes, headerMime, fileName2);
-      const base643 = bytes.toString("base64");
-      const meta3 = {
+      const mimeType2 = resolveDownloadMime(bytes, headerMime, fileName2);
+      return await buildInlineDelivery({
         fileId,
         fileName: fileName2,
-        mimeType,
-        sizeBytes: bytes.length,
-        mode: "inline"
-      };
-      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(fileName2)}`,
-        mimeType,
-        blob: base643
-      } }] };
+        mimeType: mimeType2,
+        bytes,
+        forcedInline,
+        options: deliveryOptions
+      });
     }
     let dest;
     const safeName = basename2(cached2.fileName);
@@ -40308,29 +41612,34 @@ ${text}` : text);
     } else {
       dest = join5(getAttachmentsDir(), `${fileId}-${safeName}`);
     }
+    const extractOnDisk = args.extract === true;
     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: resolveDownloadMime(Buffer.alloc(0), cached2.mimeType, cached2.fileName),
-        sizeBytes: cached2.sizeBytes,
-        fileName: cached2.fileName,
-        note: "already downloaded"
-      });
+      const onDisk = extractOnDisk ? attachmentIO.readDownloaded(dest) : null;
+      if (!extractOnDisk || onDisk) {
+        const mimeType2 = resolveDownloadMime(onDisk ?? Buffer.alloc(0), cached2.mimeType, cached2.fileName);
+        return jsonResponse({
+          fileId,
+          path: dest,
+          mimeType: mimeType2,
+          sizeBytes: cached2.sizeBytes,
+          fileName: cached2.fileName,
+          note: "already downloaded",
+          ...onDisk ? await tryExtract(onDisk, mimeType2, cached2.fileName, deliveryOptions) : {}
+        });
+      }
     }
     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;
+    const mimeType = resolveDownloadMime(response.body, response.contentType ?? cached2.mimeType, fileName);
     return jsonResponse({
       fileId,
       path: dest,
-      mimeType: resolveDownloadMime(response.body, response.contentType ?? cached2.mimeType, fileName),
+      mimeType,
       sizeBytes: response.body.length,
-      fileName
+      fileName,
+      ...extractOnDisk ? await tryExtract(response.body, mimeType, fileName, deliveryOptions) : {}
     });
   });
   server.registerTool("ofw_sync_messages", {
@@ -40338,7 +41647,7 @@ ${text}` : text);
     annotations: { readOnlyHint: false },
     inputSchema: {
       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(),
+      fetchUnreadBodies: external_exports.boolean().describe('If true, also fetch bodies for unread inbox messages \u2014 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: 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()
     }
@@ -40346,7 +41655,10 @@ ${text}` : text);
     const cache = cacheProvider();
     const result = await syncAll(client2, {
       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);
@@ -40357,16 +41669,16 @@ ${text}` : text);
     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 },
+    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". 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` \u2014 "draft" | "sent" | "received" | "deleted" | "unknown" \u2014 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: 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()
+      messageIds: external_exports.array(external_exports.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 \u2014 none of those can stamp the record. Anything else is skipped \u2014 see allowMarkRead.`).optional(),
+      allowMarkRead: external_exports.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 \u2014 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;
+    const allowMarkRead = getAllowMarkRead() && (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"]);
@@ -40380,12 +41692,14 @@ ${text}` : text);
         { label: "ofw-mcp", context: "GET /pub/v1/messageFolders (ofw_check_freshness)" }
       );
       const sys = data.systemFolders ?? [];
+      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;
         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 neverSynced = state === null;
+        const historyComplete = !neverSynced && state.resumePage === null;
         const inSync = serverCount === null || !historyComplete ? null : serverCount === cachedCount;
         folders.push({
           folder,
@@ -40395,56 +41709,13 @@ ${text}` : text);
           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."
+          ...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." : 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 probed = await probeIds(client2, cache, ids, { allowMarkRead });
+    requestsUsed += probed.requests;
+    const items = probed.items;
     const payload = {
       checkedAt: (/* @__PURE__ */ new Date()).toISOString(),
       requestsUsed,
@@ -40456,6 +41727,132 @@ ${text}` : text);
     }
     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 \u2014 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?" \u2014 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: external_exports.array(external_exports.number()).describe(`Message/draft ids to resolve to a live state (combined with draftKeys, max ${MAX_FRESHNESS_IDS} probes per call).`).optional(),
+      draftKeys: external_exports.array(external_exports.string()).describe("Stable draft keys (from ofw_save_draft / ofw_list_drafts) to resolve to their CURRENT id and state.").optional(),
+      includeDraftInventory: external_exports.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: external_exports.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 \u2014 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 ?? [];
+    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;
+    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 = [];
+    let drafts;
+    let inventoryComplete = true;
+    let inventoryFreshness;
+    if (wantInventory) {
+      const sync = await syncAll(client2, {
+        folders: ["drafts"],
+        maxRequests: getSyncMaxRequests()
+      }, cache);
+      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");
+      }
+    }
+    const requested = [];
+    if (targets.length > 0) {
+      const resolved = /* @__PURE__ */ 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 = /* @__PURE__ */ 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 !== void 0) toProbe.add(chain.currentId);
+        }
+      }
+      const probed = await probeIds(client2, 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 === void 0) {
+          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 !== void 0 || 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: (/* @__PURE__ */ new Date()).toISOString(),
+      probeRequests,
+      ...drafts !== void 0 ? { drafts, draftCount: drafts.length, draftInventoryComplete: inventoryComplete } : {},
+      ...requested.length > 0 ? { requested } : {},
+      complete,
+      ...complete ? {} : { incompleteReasons: incomplete, note: "complete:false \u2014 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 !== void 0 ? { freshness: inventoryFreshness } : {}
+    });
+  });
+}
+function decorate(item) {
+  return item.state === "sent" ? { ...item, sentMessageId: item.id } : { ...item };
 }
 async function deleteOFWMessages(client2, ids) {
   const form = new FormData();
@@ -40719,6 +42116,14 @@ function draftFromDb(r) {
     listData: JSON.parse(r.list_data_json)
   };
 }
+function lineageFromDb(r) {
+  return {
+    id: r.id,
+    draftKey: r.draft_key,
+    previousId: r.previous_id,
+    recordedAt: r.recorded_at
+  };
+}
 function attachmentFromDb(r) {
   return {
     fileId: r.file_id,
@@ -40774,6 +42179,17 @@ var SCHEMA_STATEMENTS = [
      key TEXT PRIMARY KEY,
      value TEXT NOT NULL
    )`,
+  // v3: draft identity chain. One row per OFW id, all the ids of one logical
+  // document sharing a `draft_key`. Survives ofw_save_draft's create-then-delete
+  // replacement AND the transition to a sent message, so "what happened to the
+  // draft I was editing?" is answerable without guessing which id is current.
+  `CREATE TABLE IF NOT EXISTS draft_lineage (
+     id INTEGER PRIMARY KEY,
+     draft_key TEXT NOT NULL,
+     previous_id INTEGER,
+     recorded_at TEXT NOT NULL
+   )`,
+  `CREATE INDEX IF NOT EXISTS idx_draft_lineage_key ON draft_lineage(draft_key, recorded_at, id)`,
   // v2: attachments table. Idempotent — IF NOT EXISTS.
   `CREATE TABLE IF NOT EXISTS attachments (
      file_id INTEGER PRIMARY KEY,
@@ -40792,7 +42208,7 @@ var MIGRATIONS = [
   // Resumable deep-sync cursor. Absent/NULL → SyncState.resumePage null.
   "ALTER TABLE sync_state ADD COLUMN resume_page INTEGER"
 ];
-var SCHEMA_VERSION = "2";
+var SCHEMA_VERSION = "3";
 function buildMessageFilter(opts) {
   const wheres = [];
   const params = [];
@@ -40977,6 +42393,10 @@ var OFWCacheCore = class {
     );
     return rows.map(draftFromDb);
   }
+  countDrafts() {
+    const r = this.db.get("SELECT COUNT(*) as n FROM drafts", []);
+    return r?.n ?? 0;
+  }
   deleteDraft(id) {
     this.db.run("DELETE FROM drafts WHERE id = ?", [id]);
   }
@@ -40984,6 +42404,57 @@ var OFWCacheCore = class {
     const rows = this.db.all("SELECT id FROM drafts", []);
     return rows.map((r) => r.id);
   }
+  /**
+   * Link an id into a draft's identity chain. Upserts on id: re-recording the
+   * same id (e.g. a retried save) rewrites its link rather than duplicating it,
+   * so `getDraftLineage` can never report one id twice.
+   */
+  recordDraftLineage(row) {
+    this.db.run(
+      `INSERT INTO draft_lineage (id, draft_key, previous_id, recorded_at) VALUES (?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         draft_key=excluded.draft_key,
+         previous_id=excluded.previous_id,
+         recorded_at=excluded.recorded_at`,
+      [
+        row.id,
+        requireString("draft_lineage.draftKey", row.draftKey),
+        nullish3(row.previousId),
+        requireString("draft_lineage.recordedAt", row.recordedAt)
+      ]
+    );
+  }
+  getDraftLineageById(id) {
+    const r = this.db.get("SELECT * FROM draft_lineage WHERE id = ?", [id]);
+    return r ? lineageFromDb(r) : null;
+  }
+  /**
+   * Batch read — one query for a whole page of drafts. On the Durable Object
+   * backend each cache call is a subrequest, so a per-draft lookup would spend
+   * the caller's sync budget on bookkeeping.
+   */
+  getDraftLineageByIds(ids) {
+    if (ids.length === 0) return [];
+    const placeholders = ids.map(() => "?").join(", ");
+    const rows = this.db.all(
+      `SELECT * FROM draft_lineage WHERE id IN (${placeholders})`,
+      ids
+    );
+    return rows.map(lineageFromDb);
+  }
+  /**
+   * Every link in one chain, OLDEST FIRST — so the last element is the chain's
+   * current id. Ordered by recorded_at then id: two links written inside the
+   * same millisecond tie-break on id, and OFW mints ids monotonically, so the
+   * newer replacement always sorts last.
+   */
+  getDraftLineage(draftKey) {
+    const rows = this.db.all(
+      "SELECT * FROM draft_lineage WHERE draft_key = ? ORDER BY recorded_at ASC, id ASC",
+      [draftKey]
+    );
+    return rows.map(lineageFromDb);
+  }
   getSyncState(folder) {
     const r = this.db.get("SELECT last_sync_at, newest_id, resume_page FROM sync_state WHERE folder = ?", [folder]);
     if (!r) return null;
@@ -41119,12 +42590,27 @@ var LocalCacheStore = class {
   async listDrafts(opts) {
     return this.core.listDrafts(opts);
   }
+  async countDrafts() {
+    return this.core.countDrafts();
+  }
   async deleteDraft(id) {
     this.core.deleteDraft(id);
   }
   async listDraftIds() {
     return this.core.listDraftIds();
   }
+  async recordDraftLineage(row) {
+    this.core.recordDraftLineage(row);
+  }
+  async getDraftLineageById(id) {
+    return this.core.getDraftLineageById(id);
+  }
+  async getDraftLineageByIds(ids) {
+    return this.core.getDraftLineageByIds(ids);
+  }
+  async getDraftLineage(draftKey) {
+    return this.core.getDraftLineage(draftKey);
+  }
   async getSyncState(folder) {
     return this.core.getSyncState(folder);
   }
@@ -41228,7 +42714,7 @@ var nodeCacheProvider = () => nodeCache ??= OFWCache.open(getCacheDbPath());
 var nodeAttachmentIO = new NodeAttachmentIO();
 await runMcp({
   name: "ofw",
-  version: "2.7.1",
+  version: "2.9.0",
   // x-release-please-version
   deps: client,
   tools: [