ofw-mcp 2.8.0 → 2.9.1

package/dist/cache/store.js

@@ -32,6 +32,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,
@@ -93,6 +101,17 @@ export const 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,
@@ -119,7 +138,7 @@ export const MIGRATIONS = [
     'ALTER TABLE sync_state ADD COLUMN resume_page INTEGER',
 ];
 /** The schema version stamped into the `meta` table on open. */
-export const SCHEMA_VERSION = '2';
+export const SCHEMA_VERSION = '3';
 // Build the WHERE clause + bound params for message queries. listMessages and
 // countMessages share this so the filter semantics can't drift.
 function buildMessageFilter(opts) {
@@ -302,6 +321,11 @@ export class OFWCacheCore {
         const rows = this.db.all('SELECT * FROM drafts ORDER BY modified_at DESC, id DESC LIMIT ? OFFSET ?', [opts.size, offset]);
         return rows.map(draftFromDb);
     }
+    countDrafts() {
+        const r = this.db.get('SELECT COUNT(*) as n FROM drafts', []);
+        /* v8 ignore next -- SELECT COUNT(*) always returns exactly one row; the ?./?? are defensive */
+        return r?.n ?? 0;
+    }
     deleteDraft(id) {
         this.db.run('DELETE FROM drafts WHERE id = ?', [id]);
     }
@@ -309,6 +333,45 @@ export class OFWCacheCore {
         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), nullish(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)
@@ -444,12 +507,27 @@ export class LocalCacheStore {
     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);
     }

package/dist/config.js

@@ -124,6 +124,24 @@ export function getAllowMarkRead() {
 export function getFetchUnreadBodies() {
     return parseBoolEnv('OFW_FETCH_UNREAD_BODIES');
 }
+/**
+ * Default for the read tools' `autoRefresh` arg.
+ *
+ * When a cached read comes back EMPTY and the cache is not `fresh`, the tools
+ * refuse to report that emptiness (see UNVERIFIED_EMPTY in tools/messages.ts):
+ * an empty result from a 207-minute-old cache is shaped identically to a
+ * verified "nothing there", and answering "no, it wasn't sent" from one is how
+ * a false negative becomes a confident statement about a legal record.
+ *
+ * The refusal names its remedy, so the default (false) costs one extra call.
+ * Set OFW_AUTO_REFRESH=true and the tools instead sync the backing folders
+ * themselves and answer from the refreshed cache — same guarantee, no round
+ * trip. Never silently degrades: if the refresh does not make the read
+ * verifiable, the refusal still fires.
+ */
+export function getAutoRefreshStaleReads() {
+    return parseBoolEnv('OFW_AUTO_REFRESH');
+}
 // Default for ofw_download_attachment's `inline` arg when the caller doesn't
 // pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as
 // MCP content blocks by default (skipping disk) — useful on sandboxed MCP

package/dist/index.js

@@ -35,7 +35,7 @@ const nodeAttachmentIO = new NodeAttachmentIO();
 // always succeeds before any credential check runs.
 await runMcp({
     name: 'ofw',
-    version: '2.8.0', // x-release-please-version
+    version: '2.9.1', // x-release-please-version
     deps: client,
     tools: [
         registerUserTools,

package/dist/sync.js

@@ -94,6 +94,10 @@ export async function resolveFolderIds(client, store) {
     // label an uncached message sent-vs-inbox from the detail payload's own folder
     // id, instead of hard-defaulting to inbox.
     await store.setMeta('sent_folder_id', ids.sent);
+    // And inbox, which completes the map a lifecycle probe needs to turn a detail
+    // payload's own folder id into "draft" / "sent" / "received" (see
+    // tools/lifecycle.ts). Without all three, a probe can only say "unknown".
+    await store.setMeta('inbox_folder_id', ids.inbox);
     return ids;
 }
 // Required fields are the ones the sync loop reads unguarded (id keys the

package/dist/timestamps.js

@@ -0,0 +1,282 @@
+// Canonical timestamp handling for every structured OFW response.
+//
+// A single response object used to mix zones: `sentAt`/`viewedAt`/`modifiedAt`
+// came from OFW's API as NAIVE local wall-clock ("2026-07-27T23:31:09", no
+// offset), while `fetchedBodyAt` and `freshness.asOf` were stamped by us as UTC
+// with a `Z`. Nothing in the payload said which was which, so a reader assumed
+// one zone for both and was wrong by the UTC offset on half the fields.
+//
+// The failure that matters is the calendar DAY. A message sent 10:38 PM Eastern
+// reported as 02:38 lands on the following day, and in a co-parenting record
+// that decides which custody day an event belongs to and whether it beat a
+// 48-hour response window.
+//
+// Every value that survives detection is rewritten to ISO-8601 WITH an
+// explicit offset and paired with a `<key>Display` sibling rendered in the
+// operator's zone, weekday included, because a wrong weekday is what makes a
+// date-boundary error visible at a glance.
+//
+// NOTE: this mirrors the helper in gogcli-mcp. Both connectors had the same
+// defect, and the two copies should collapse into @chrischall/mcp-utils once
+// that package next ships.
+import { readEnvVar } from '@chrischall/mcp-utils';
+// Fallback display zone for this deployment. IANA name, never a fixed offset —
+// a hardcoded -04:00 would be an hour wrong from November through March.
+export const DEFAULT_DISPLAY_TZ = 'America/New_York';
+function isValidTimeZone(tz) {
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// The zone all *Display fields render in, and the zone a NAIVE source value is
+// assumed to be wall-clock in. OFW's API reports naive local times in the
+// account's own zone, so this must match it. An invalid DISPLAY_TZ falls back
+// rather than throwing, so a typo degrades the label instead of breaking
+// every tool.
+export function displayTimeZone() {
+    const configured = readEnvVar('DISPLAY_TZ');
+    if (configured && isValidTimeZone(configured))
+        return configured;
+    return DEFAULT_DISPLAY_TZ;
+}
+// Offset of `tz` at a given instant, as "+HH:MM"/"-HH:MM". Uses the IANA
+// database via Intl, so DST is handled per-instant rather than per-zone.
+function offsetAt(instant, tz) {
+    // Derived arithmetically rather than parsed out of Intl's "GMT-04:00" label:
+    // the gap between the zone's wall clock and the instant IS the offset, and
+    // zone offsets are always whole minutes.
+    const w = wallPartsIn(instant, tz);
+    const asUTC = Date.UTC(w.year, w.month - 1, w.day, w.hour, w.minute, w.second, instant.getUTCMilliseconds());
+    const minutes = Math.round((asUTC - instant.getTime()) / 60_000);
+    const sign = minutes < 0 ? '-' : '+';
+    const abs = Math.abs(minutes);
+    return `${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`;
+}
+// Wall-clock fields of `instant` as seen in `tz`, via Intl so the IANA rules
+// (including DST) apply.
+// Intl.DateTimeFormat construction dominates the cost here, and a 50-message
+// listing formats hundreds of timestamps. Cache one formatter per zone.
+const wallPartsFormatters = new Map();
+const displayFormatters = new Map();
+function wallPartsFormatter(tz) {
+    let fmt = wallPartsFormatters.get(tz);
+    if (!fmt) {
+        fmt = buildWallPartsFormatter(tz);
+        wallPartsFormatters.set(tz, fmt);
+    }
+    return fmt;
+}
+function wallPartsIn(instant, tz) {
+    const parts = wallPartsFormatter(tz).formatToParts(instant);
+    const out = {};
+    for (const p of parts) {
+        if (p.type !== 'literal')
+            out[p.type] = Number(p.value);
+    }
+    return out;
+}
+function buildWallPartsFormatter(tz) {
+    return new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        // h23 pins midnight to hour 00; without it some ICU builds render hour 24.
+        hourCycle: 'h23',
+    });
+}
+// Interpret naive wall-clock fields as an instant in `tz`. There is no direct
+// inverse of the zone rules, so guess UTC, measure how far the guess lands from
+// the requested wall time in that zone, and correct. Two passes settle the case
+// where the correction itself crosses a DST boundary.
+function wallTimeToInstant(y, mo, d, h, mi, s, ms, tz) {
+    let guess = Date.UTC(y, mo - 1, d, h, mi, s, ms);
+    for (let i = 0; i < 2; i += 1) {
+        const seen = wallPartsIn(new Date(guess), tz);
+        const seenUTC = Date.UTC(seen.year, seen.month - 1, seen.day, seen.hour, seen.minute, seen.second, ms);
+        const drift = Date.UTC(y, mo - 1, d, h, mi, s, ms) - seenUTC;
+        if (drift === 0)
+            break;
+        guess += drift;
+    }
+    return new Date(guess);
+}
+function pad(n, width = 2) {
+    return String(n).padStart(width, '0');
+}
+// Render `instant` as ISO-8601 carrying `offset`'s wall time and label.
+function isoWithOffset(instant, tz, offset) {
+    const w = wallPartsIn(instant, tz);
+    const msPart = instant.getUTCMilliseconds();
+    const frac = msPart ? `.${pad(msPart, 3)}` : '';
+    return `${pad(w.year, 4)}-${pad(w.month)}-${pad(w.day)}T${pad(w.hour)}:${pad(w.minute)}:${pad(w.second)}${frac}${offset}`;
+}
+// The one place an instant becomes user-visible text. Every emitted timestamp
+// goes through here, so no call site can reintroduce a naive value.
+export function formatInstant(instant, tz = displayTimeZone()) {
+    const offset = offsetAt(instant, tz);
+    let fmt = displayFormatters.get(tz);
+    if (!fmt) {
+        fmt = new Intl.DateTimeFormat('en-US', {
+            timeZone: tz,
+            weekday: 'short',
+            month: 'short',
+            day: 'numeric',
+            year: 'numeric',
+            hour: 'numeric',
+            minute: '2-digit',
+            timeZoneName: 'short',
+        });
+        displayFormatters.set(tz, fmt);
+    }
+    return { iso: isoWithOffset(instant, tz, offset), display: fmt.format(instant) };
+}
+// Keys whose STRING values are timestamps. Deliberately an allowlist rather
+// than a name pattern: a value must ALSO match a timestamp shape below, so both
+// the key and the value have to agree before anything is touched. That keeps
+// user-authored content (a message body quoting a date, an expense description)
+// from ever being rewritten.
+const TIMESTAMP_KEYS = new Set([
+    // OFW: naive local wall-clock from the API.
+    'sentAt',
+    'viewedAt',
+    'modifiedAt',
+    'createdAt',
+    'dueAt',
+    'occurredAt',
+    // OFW: UTC instants we stamp ourselves.
+    'fetchedBodyAt',
+    'fetchedAt',
+    'syncedAt',
+    'downloadedAt',
+    'recordedAt',
+    'expiresAt',
+    // Freshness/sync bookkeeping. These sit in the SAME object as `asOf`, so
+    // omitting them left the freshness block emitting two zones at once — the
+    // exact defect this module exists to remove. Enumerated from a sweep of
+    // emitted field names rather than from the ones a bug report happened to
+    // mention.
+    'asOf',
+    'checkedAt',
+    'lastVerifiedAt',
+    'oldestVerifiedAt',
+    'lastServerSyncAt',
+    'lastSyncAt',
+    // OFW API inner shape: `date: { dateTime }`, `viewed: { dateTime }`.
+    'dateTime',
+    // Generic.
+    'date',
+    'updated',
+    'lastModified',
+    'expirationTime',
+]);
+// Deliberately NOT timestamps: `startDate`/`endDate` are YYYY-MM-DD and
+// `startTime`/`endTime` are HH:mm — a calendar date and a wall time, neither of
+// which denotes an instant. Attaching an offset would invent information. The
+// shape guards below would reject them anyway; this records the intent.
+// Keys that hold a zone NAME rather than an instant. They cannot match a
+// timestamp shape anyway, but naming them documents the hazard.
+const ZONE_NAME_KEYS = new Set(['timeZone', 'timezone']);
+const RFC3339_WITH_OFFSET = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d{1,9}))?(Z|[+-]\d{2}:?\d{2})$/;
+const NAIVE_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d{1,9}))?$/;
+// A bare YYYY-MM-DD is a DATE, not an instant — Calendar uses it for all-day
+// events. Converting one would invent a time that the source never asserted.
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+// True when the components describe a real calendar instant. Guards against
+// Date.UTC's silent rollover of out-of-range values.
+function isRealCalendarDate(p) {
+    const utc = new Date(Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second));
+    return utc.getUTCFullYear() === p.year
+        && utc.getUTCMonth() === p.month - 1
+        && utc.getUTCDate() === p.day
+        && utc.getUTCHours() === p.hour
+        && utc.getUTCMinutes() === p.minute
+        && utc.getUTCSeconds() === p.second;
+}
+// Resolve a raw field value to an instant, or null when it is not a timestamp.
+// `assumeNaiveIn` is the zone a naive (offset-less) value is wall-clock in.
+export function parseTimestampValue(key, value, assumeNaiveIn) {
+    if (typeof value !== 'string')
+        return null;
+    const raw = value.trim();
+    if (raw === '' || DATE_ONLY.test(raw))
+        return null;
+    if (RFC3339_WITH_OFFSET.test(raw)) {
+        // The source already knows its offset; trust it verbatim.
+        const parsed = new Date(raw.replace(' ', 'T'));
+        return Number.isNaN(parsed.getTime()) ? null : parsed;
+    }
+    const naive = NAIVE_DATE_TIME.exec(raw);
+    if (naive) {
+        const [, y, mo, d, h, mi, s, frac] = naive;
+        const ms = frac ? Number(frac.padEnd(3, '0').slice(0, 3)) : 0;
+        const parts = {
+            year: Number(y), month: Number(mo), day: Number(d),
+            hour: Number(h), minute: Number(mi), second: Number(s ?? '0'),
+        };
+        // Date.UTC silently rolls impossible components over — month 99 becomes
+        // 2034, Feb 30 becomes Mar 2 — so a typo would surface as a confident wrong
+        // date rather than a rejection. The offset branch above already returns
+        // null for the same input; match it.
+        //
+        // Checked in UTC space, deliberately: validating against the ZONE's wall
+        // clock would also reject a non-existent spring-forward time like
+        // 2026-03-08 02:30 ET, and shifting such a value forward (as zone libraries
+        // do) is better than dropping a timestamp we can place to within an hour.
+        if (!isRealCalendarDate(parts))
+            return null;
+        return wallTimeToInstant(parts.year, parts.month, parts.day, parts.hour, parts.minute, parts.second, ms, assumeNaiveIn);
+    }
+    return null;
+}
+// True when a string carries no zone information — the shape this whole module
+// exists to eliminate. Used by the contract test.
+export function isNaiveTimestamp(value) {
+    return typeof value === 'string' && NAIVE_DATE_TIME.test(value.trim());
+}
+// Walk a parsed payload, rewriting every allowlisted timestamp to canonical
+// form and attaching its display sibling. Mutates and returns `node`.
+function walk(node, tz) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walk(item, tz);
+        return node;
+    }
+    if (node === null || typeof node !== 'object')
+        return node;
+    const obj = node;
+    for (const key of Object.keys(obj)) {
+        const value = obj[key];
+        if (value !== null && typeof value === 'object') {
+            walk(value, tz);
+            continue;
+        }
+        if (ZONE_NAME_KEYS.has(key) || !TIMESTAMP_KEYS.has(key))
+            continue;
+        const instant = parseTimestampValue(key, value, tz);
+        if (!instant)
+            continue;
+        const { iso, display } = formatInstant(instant, tz);
+        obj[key] = iso;
+        obj[`${key}Display`] = display;
+    }
+    return obj;
+}
+// Normalize every timestamp in a structured response payload.
+//
+// The input is CLONED before walking: response payloads routinely include live
+// cache rows, and rewriting those in place would corrupt the cache and make the
+// normalization observable on a later read. Primitives pass through untouched
+// so the seam is safe for any tool result.
+export function normalizeTimestampsInValue(value, tz = displayTimeZone()) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    return walk(structuredClone(value), tz);
+}

package/dist/tools/_shared.js

@@ -1,9 +1,19 @@
 import { expandPath as expandPathUtil, rawTextResult, textResult } from '@chrischall/mcp-utils';
 import { z } from 'zod';
 import { parseLenient } from '@chrischall/mcp-utils';
+import { normalizeTimestampsInValue } from '../timestamps.js';
 // Pretty-printed JSON tool result. Thin wrapper over @chrischall/mcp-utils'
-// `textResult` so the rest of the codebase keeps the local name.
-export const jsonResponse = textResult;
+// `textResult`, with one addition: every timestamp in the payload is rewritten
+// to ISO-8601 with an explicit offset and paired with a `<field>Display`
+// sibling in the operator's zone.
+//
+// This is the single seam every structured tool response passes through, which
+// is the point — normalizing here rather than at each call site is what makes
+// it impossible for a tool to reintroduce the naive-local values that had
+// `sentAt` and `fetchedBodyAt` silently disagreeing by the UTC offset.
+export function jsonResponse(data) {
+    return textResult(normalizeTimestampsInValue(data));
+}
 // Raw-string tool result. Wrapper over @chrischall/mcp-utils' `rawTextResult`.
 export const textResponse = rawTextResult;
 // A STRUCTURED failure: the machine-readable payload of `jsonResponse` plus
@@ -11,7 +21,11 @@ export const textResponse = rawTextResult;
 // we declined to overwrite) without being mistaken for a successful write.
 // mcp-utils' `errorResult` only carries a string.
 export function jsonErrorResponse(data) {
-    return { ...textResult(data), isError: true };
+    // Routed through jsonResponse, not textResult: a refusal payload carries the
+    // same freshness block as the success path, and emitting it unnormalized made
+    // an UNVERIFIED_EMPTY response report `asOf` in UTC while every successful
+    // response reported it with an offset.
+    return { ...jsonResponse(data), isError: true };
 }
 // OFW API shape for `recipients[]` on message/draft list and detail
 // responses. Used wherever we validate the response of a `/pub/v3/messages*`

package/dist/tools/draft-freshness.js

@@ -39,23 +39,40 @@ const ServerDraftSchema = z.looseObject({
     body: z.string().optional(),
     replyToId: z.number().nullable().optional(),
     recipients: z.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: z.looseObject({
+        id: z.union([z.string(), z.number()]).optional(),
+        name: z.string().optional(),
+    }).nullable().optional(),
+    date: z.looseObject({ dateTime: z.string().optional() }).nullable().optional(),
 });
 function isNotFound(e) {
     return e instanceof Error && /OFW API error: 404\b/.test(e.message);
 }
 /**
- * Read a draft's AUTHORITATIVE state straight from OFW, bypassing the cache.
+ * Read a message's AUTHORITATIVE state straight from OFW, bypassing the cache.
  *
- * Returns `null` when the draft no longer exists (404). Any other failure
- * throws, and the callers in messages.ts abort on ALL of them: a freshness
- * check that could not run must never wave the write through.
+ * Returns `null` when it no longer exists (404, or an empty body — OFW's other
+ * way of saying "no such message"). Any other failure throws.
  *
- * Most failures throw `DraftFreshnessError` from this function, but not all —
- * a strict `parseLenient` mismatch on the response throws `McpToolError`
- * instead. Callers must not assume the narrower type (the catch blocks read
- * only `.message`, which every Error carries).
+ * Most failures throw `DraftFreshnessError`, but not all — a strict
+ * `parseLenient` mismatch throws `McpToolError` instead. Callers must not assume
+ * the narrower type (the catch blocks read only `.message`, which every Error
+ * carries).
  */
-export async function fetchServerDraft(client, id) {
+export async function fetchMessageSnapshot(client, id) {
     let raw;
     try {
         raw = await client.request('GET', `/pub/v3/messages/${id}`);
@@ -76,12 +93,28 @@ export async function fetchServerDraft(client, 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 === undefined ? null : String(detail.folder.id),
+        folderName: detail.folder?.name ?? null,
+        dateTime: detail.date?.dateTime ?? null,
     };
 }
+/**
+ * The content-only view of {@link fetchMessageSnapshot}, used by the
+ * destructive-draft guard, which cares what the draft SAYS, not where it lives.
+ *
+ * Returns `null` when the draft no longer exists. Any other failure throws, and
+ * the callers in messages.ts abort on ALL of them: a freshness check that could
+ * not run must never wave the write through.
+ */
+export async function fetchServerDraft(client, id) {
+    return (await fetchMessageSnapshot(client, id))?.content ?? null;
+}
 /**
  * The fields whose divergence constitutes a REAL conflict — the actual message
  * content a caller would lose if we overwrote a copy edited elsewhere. Anything