ofw-mcp 2.20.3 → 2.20.4

package/dist/bundle.js

@@ -121,9 +121,9 @@ var require_buffer_util = __commonJS({
       toBuffer,
       unmask: _unmask
     };
-    if (!process.env.WS_NO_BUFFER_UTIL) {
+    if (false) {
       try {
-        const bufferUtil = __require("bufferutil");
+        const bufferUtil = null;
         module.exports.mask = function(source, mask, output2, offset, length) {
           if (length < 48) _mask(source, mask, output2, offset, length);
           else bufferUtil.mask(source, mask, output2, offset, length);
@@ -760,9 +760,9 @@ var require_validation2 = __commonJS({
       module.exports.isValidUTF8 = function(buf) {
         return buf.length < 24 ? _isValidUTF8(buf) : isUtf8(buf);
       };
-    } else if (!process.env.WS_NO_UTF_8_VALIDATE) {
+    } else if (false) {
       try {
-        const isValidUTF8 = __require("utf-8-validate");
+        const isValidUTF8 = null;
         module.exports.isValidUTF8 = function(buf) {
           return buf.length < 32 ? _isValidUTF8(buf) : isValidUTF8(buf);
         };
@@ -38245,17 +38245,62 @@ var DEFAULT_MAX_REQUEST_BODY_SIZE = 4 * 1024 * 1024;
 
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
 var DEFAULT_ERROR_MESSAGE_MAX = 500;
+var MCP_TOOL_ERROR_KINDS = /* @__PURE__ */ new Set([
+  "no_credential",
+  "credential_rejected",
+  "edge_blocked",
+  "session_expired",
+  "verification_pending",
+  "timeout",
+  "http",
+  "transport",
+  "too_large",
+  "unknown"
+]);
 var McpToolError = class extends Error {
   /** Actionable remediation text, when one applies. */
   hint;
+  /** The upstream HTTP status this failure came from, when known. */
+  status;
+  /** What kind of failure this is, when the thrower knows. */
+  kind;
   constructor(message, opts) {
     super(message, opts?.cause !== void 0 ? { cause: opts.cause } : void 0);
     this.name = "McpToolError";
     if (opts?.hint !== void 0)
       this.hint = opts.hint;
+    if (opts?.status !== void 0)
+      this.status = opts.status;
+    if (opts?.kind !== void 0)
+      this.kind = opts.kind;
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+var DECLARATION_CAUSE_DEPTH = 4;
+function firstDeclared(err, read) {
+  let cur = err;
+  for (let depth = 0; depth < DECLARATION_CAUSE_DEPTH && cur !== null && typeof cur === "object"; depth++) {
+    const found = read(cur);
+    if (found !== void 0)
+      return found;
+    cur = cur.cause;
+  }
+  return void 0;
+}
+function errorStatusOf(err) {
+  return firstDeclared(err, (link2) => {
+    const e = link2;
+    if (typeof e.status === "number")
+      return e.status;
+    return typeof e.statusCode === "number" ? e.statusCode : void 0;
+  });
+}
+function errorKindOf(err) {
+  return firstDeclared(err, (link2) => {
+    const k = link2.kind;
+    return typeof k === "string" && MCP_TOOL_ERROR_KINDS.has(k) ? k : void 0;
+  });
+}
 function createHelpfulError(message, opts) {
   return new McpToolError(message, opts);
 }
@@ -38280,7 +38325,7 @@ var API_KEY_RE = new RegExp([
   // webhook signing secret (Stripe-style)
 ].map((p) => `\\b${p}`).join("|"), "g");
 var GOOGLE_OAUTH_TOKEN_RE = /(?<![A-Za-z0-9+/])(?:ya29\.|1\/\/)[A-Za-z0-9._-]{8,}/g;
-var QUERY_SECRET_RE = new RegExp(`([?&](?:(?:access|refresh|id|auth|session|csrf|xsrf)[_-]?token|client[_-]?secret|api[_-]?secret|api[_-]?key|password|passwd|signature|token|key|sig|(?:php|j)?sess(?:ion)?[_-]?id|sid|x[-_]${HEADER_NAME_RUN}?(?:api[-_]?key|token|secret|auth)${HEADER_NAME_RUN})=)[^&#\\s"'<>\`]+`, "gi");
+var QUERY_SECRET_RE = new RegExp(`([?&](?:(?:access|refresh|id|auth|session|csrf|xsrf)[_-]?token|client[_-]?secret|api[_-]?secret|api[_-]?key|password|passwd|signature|token|key|sig|(?:code[_-]?)?verifier|(?:php|j)?sess(?:ion)?[_-]?id|sid|x[-_]${HEADER_NAME_RUN}?(?:api[-_]?key|token|secret|auth)${HEADER_NAME_RUN})=)[^&#\\s"'<>\`]+`, "gi");
 var OAUTH_CODE_RE = /([?&]code=)(?=[^&#\s"'<>`]{16,})[^&#\s"'<>`]+/gi;
 var FORM_PASSWORD_RE = /((?:^|[\s,;:"'(\[{])(?:password|passwd)=)[^&#\s"'<>`]+/gim;
 var HEADER_SECRET_RE = new RegExp(`(\\b(?:x[-_]${HEADER_NAME_RUN}?(?:api[-_]?key|token|secret|auth)${HEADER_NAME_RUN}|api[-_]?key)\\s*:\\s*)[^\\s,;"'<>\`]+`, "gi");
@@ -38291,6 +38336,8 @@ var JSON_SECRET_KEYS = [
   "api[_-]?secret",
   "(?:x[_-])?api[_-]?key",
   "private[_-]?key",
+  "code[_-]?verifier",
+  // PKCE; a bare `verifier` key is too generic for JSON
   `x[_-]${HEADER_NAME_RUN}?(?:api[_-]?key|token|secret|auth)${HEADER_NAME_RUN}`,
   // bounded like HEADER_SECRET_RE
   "(?:proxy-)?authorization",
@@ -38755,7 +38802,7 @@ function readEnvVar(key, opts = {}) {
   if (typeof raw === "string") {
     const trimmed = raw.trim();
     if (trimmed.length > 0 && trimmed !== "undefined" && trimmed !== "null" && !PLACEHOLDER_RE.test(trimmed)) {
-      return trimmed;
+      return opts.trim === false ? raw : trimmed;
     }
   }
   return opts.default;
@@ -38966,12 +39013,19 @@ function boundArgs(args) {
 }
 function confirmationFromEnv(options) {
   const { tool, account, confirmToken, subject, instruction, args, env = process.env, spent: callerSpent, ...rest } = options;
+  if (args === void 0 || args === null) {
+    throw new TypeError(`confirmationFromEnv: ${tool} passed no args; pass the tool's validated arguments ({} for a tool with none).`);
+  }
   const spent = callerSpent ?? spentTokenStoreFromEnv(env);
   const mode = readConfirmMode(env);
   const ttlSeconds = readConfirmTtl(env);
   const elicitationOff = readConfirmElicitation(env) === "off";
-  const bound = args === void 0 ? void 0 : boundArgs(args);
-  const bindingAdded = bound === void 0 || rest.binding ? rest : { ...rest, binding: { key: confirmKeyFromEnv(env), args: bound, ttlSeconds: ttlSeconds ?? DEFAULT_TTL_SECONDS2 } };
+  const bound = boundArgs(args);
+  const elicitationBound = account === void 0 ? { args: bound } : { account, args: bound };
+  const bindingAdded = rest.binding ? rest : {
+    ...rest,
+    binding: { key: confirmKeyFromEnv(env), args: elicitationBound, ttlSeconds: ttlSeconds ?? DEFAULT_TTL_SECONDS2 }
+  };
   const confirmation = elicitationOff ? { ...bindingAdded, elicitation: false } : bindingAdded;
   if (mode === "refuse" || ttlSeconds === void 0) {
     const reason = mode === "refuse" ? REFUSE_HINT : BAD_TTL_HINT;
@@ -38981,7 +39035,7 @@ function confirmationFromEnv(options) {
       unsupportedNote: confirmation.unsupportedNote ? `${confirmation.unsupportedNote} ${hint}` : hint
     };
   }
-  const boundSubject = bound === void 0 ? subject : async () => {
+  const boundSubject = async () => {
     const read = await subject();
     if ("content" in read)
       return read;
@@ -39008,12 +39062,14 @@ var SERVER_PROTOCOL_VERSIONS = Object.freeze([
   ...SUPPORTED_PROTOCOL_VERSIONS
 ]);
 function hintResultOrRethrow(err) {
+  if (err instanceof ProtocolError && err.code === ProtocolErrorCode.UrlElicitationRequired)
+    throw err;
   if (err instanceof McpToolError && err.hint) {
     return errorResult(`${err.message}
 
 Hint: ${err.hint}`);
   }
-  throw err;
+  return errorResult(messageOf(err));
 }
 function mcpRequestFrom(args) {
   const ctx = args.at(-1);
@@ -39454,6 +39510,8 @@ function parseContentDispositionFilename(header) {
 // node_modules/@chrischall/mcp-utils/dist/http/index.js
 var RateLimitedError = class extends Error {
   status = 429;
+  /** `'http'`: the far side answered, with a 429 (see `status`). */
+  kind = "http";
   retryAfterMs;
   constructor(service, retryAfterMs) {
     super(`Rate limited (429) by ${service} after retries.`);
@@ -39464,6 +39522,8 @@ var RateLimitedError = class extends Error {
 };
 var RequestTimeoutError = class extends Error {
   timeoutMs;
+  /** Always `'timeout'` unless a subclass says otherwise. */
+  kind = "timeout";
   constructor(service, timeoutMs) {
     super(`Request to ${service} timed out after ${timeoutMs}ms.`);
     this.name = "RequestTimeoutError";
@@ -39483,6 +39543,8 @@ var ApiError = class extends Error {
 var EdgeBlockedError = class extends ApiError {
   /** Which edge refused the request, e.g. `'CloudFront'` or `'Cloudflare'`. */
   vendor;
+  /** Always `'edge_blocked'`: the credential was never judged. */
+  kind = "edge_blocked";
   /**
    * @param where The service the request was for, and — when the thrower knows
    *   it — the method and path, which the message names.
@@ -39565,7 +39627,7 @@ var PositiveInt = external_exports.number().int().positive();
 var NonNegInt = external_exports.number().int().nonnegative();
 var NonEmptyString = external_exports.string().min(1);
 var IsoDate = external_exports.iso.date();
-var IsoTime = external_exports.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, "must be HH:MM (24h), e.g. 19:30");
+var IsoTime = external_exports.string().regex(/^([01]?\d|2[0-3]):[0-5]\d$/, "must be HH:MM (24h), e.g. 19:30").overwrite((v) => v.padStart(5, "0"));
 var NumericIdString = external_exports.string().regex(/^\d+$/, "must be a numeric id (digits only)").describe("A numeric id string (digits only), safe to interpolate into a URL path.");
 var SafePathSegment = external_exports.string().min(1).regex(/^[^/?#\s]+$/, 'must not contain "/", "?", "#", or whitespace').refine((v) => !v.includes(".."), 'must not contain ".."').describe('A single URL path segment, safe to interpolate: no "/", "..", "?", "#", or whitespace.');
 var schemaOrigin = external_exports.string().optional().describe("Portal origin (e.g. https://<vendor>.example.co) selecting which active session to use. Optional when only one session is active.");
@@ -40124,7 +40186,9 @@ var TokenManager = class {
   /** Spend `rt`, then install and persist what comes back. */
   async exchange(rt) {
     if (rt === void 0) {
-      throw new Error("TokenManager: cannot refresh \u2014 no refresh token is available.");
+      throw new McpToolError("TokenManager: cannot refresh \u2014 no refresh token is available.", {
+        kind: "no_credential"
+      });
     }
     const tok = await this.refreshFn(rt);
     this.tokens = {
@@ -46401,12 +46465,6 @@ var BootstrapDisabledError = class extends Error {
 };
 
 // node_modules/@chrischall/mcp-utils/dist/healthcheck/index.js
-function statusOf2(err) {
-  if (typeof err !== "object" || err === null)
-    return void 0;
-  const s = err.status ?? err.statusCode;
-  return typeof s === "number" ? s : void 0;
-}
 var CREDENTIAL_ARMS = /* @__PURE__ */ new Set([
   "ok",
   "no_credential",
@@ -46422,6 +46480,9 @@ var CREDENTIAL_ARMS = /* @__PURE__ */ new Set([
 function isArm(kind) {
   return kind !== void 0 && CREDENTIAL_ARMS.has(kind);
 }
+function fromSource(source) {
+  return source !== null ? ` from '${source}'` : "";
+}
 function credentialHint(arm, prefix, hostLabel, source) {
   switch (arm) {
     case "ok":
@@ -46429,15 +46490,15 @@ function credentialHint(arm, prefix, hostLabel, source) {
     case "no_credential":
       return `No credential resolved. Nothing was available to authenticate with \u2014 sign in and reconnect the connector so ${prefix} receives a token, or set the documented environment variable.`;
     case "credential_rejected":
-      return `${hostLabel} rejected the credential from '${source}'. It is present but no longer valid \u2014 most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
+      return `${hostLabel} rejected the credential${fromSource(source)}. It is present but no longer valid \u2014 most often expired or revoked upstream. Re-authenticate and reconnect; retrying will not fix it.`;
     case "edge_blocked":
       return `${hostLabel} refused the request at its CDN/WAF before it reached the API, so the credential${source !== null ? ` from '${source}'` : ""} was never judged \u2014 re-signing in or rotating it will not help. This is usually a block on this host's IP address or request fingerprint: route through the ContextMint Bridge if this connector supports it, or retry later from a different network.`;
     case "session_expired":
-      return `The credential from '${source}' is configured, but no session is live \u2014 ${hostLabel} served a sign-in page rather than the data. Sign in again; a cookie-session portal expires these on its own, so this recurs between uses.`;
+      return `The credential${fromSource(source)} is configured, but no session is live \u2014 ${hostLabel} served a sign-in page rather than the data. Sign in again; a cookie-session portal expires these on its own, so this recurs between uses.`;
     case "verification_pending":
       return `${hostLabel} is holding the sign-in on a second factor rather than refusing it. Supply the verification code the ACCOUNT HOLDER received \u2014 the credential itself is not the problem, so changing it will not help.`;
     case "timeout":
-      return `The credential from '${source}' resolved, but ${hostLabel} did not answer in time. Usually transient \u2014 retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
+      return `${source !== null ? `The credential from '${source}' resolved, but ` : ""}${hostLabel} did not answer in time. Usually transient \u2014 retry. If it persists, ${hostLabel} is slow or unreachable from here.`;
     case "http":
       return `${hostLabel} answered with an error status that is not an auth rejection. That is USUALLY a ${hostLabel}-side problem rather than an auth one \u2014 but a 404 here more often means the probe path is wrong than that ${hostLabel} is broken, so check error.message and probe.url before concluding anything about the credential.`;
     case "transport":
@@ -46458,7 +46519,8 @@ async function runCredentialHealthcheck(args) {
     state = await resolveCredential();
   } catch (e) {
     const edge = edgeBlockOf(e);
-    const classified = classifyThrown?.(e) ?? (edge !== null ? { kind: "edge_blocked", detail: { vendor: edge.vendor } } : void 0);
+    const declared = errorKindOf(e);
+    const classified = classifyThrown?.(e) ?? (edge !== null ? { kind: "edge_blocked", detail: { vendor: edge.vendor } } : declared !== void 0 ? { kind: declared } : void 0);
     const result2 = {
       ok: false,
       // Still false, and still no source: a classification explains WHY
@@ -46505,10 +46567,11 @@ async function runCredentialHealthcheck(args) {
   try {
     await probeFn();
   } catch (e) {
-    status = statusOf2(e);
+    status = errorStatusOf(e);
     const aborted2 = e instanceof Error && e.name === "AbortError";
     const edge = edgeBlockOf(e);
-    arm = edge !== null ? "edge_blocked" : status === 401 || status === 403 ? "credential_rejected" : status !== void 0 ? "http" : aborted2 || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e)) ? "timeout" : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e)) ? "transport" : "unknown";
+    const declared = errorKindOf(e);
+    arm = edge !== null ? "edge_blocked" : declared !== void 0 ? declared : status === 401 || status === 403 ? "credential_rejected" : status !== void 0 ? "http" : aborted2 || /timeout|timed out|ETIMEDOUT/i.test(messageOf(e)) ? "timeout" : /fetch failed|ENOTFOUND|ECONNREFUSED|ECONNRESET|network/i.test(messageOf(e)) ? "transport" : "unknown";
     let kind = arm;
     let detail = edge !== null ? { vendor: edge.vendor } : void 0;
     const custom2 = classifyThrown?.(e);
@@ -46654,64 +46717,29 @@ async function loginWithPassword(username, password) {
     throw new Error(`OFW login returned unexpected response (${contentType || "no content-type"}): ${body.substring(0, 200)}`);
   }
   const data = await response.json();
+  const record2 = typeof data === "object" && data !== null ? data : null;
+  const token = record2?.auth;
+  if (typeof token !== "string" || token === "") {
+    throw new Error(describeTokenlessLogin(record2));
+  }
   return {
-    token: data.auth,
+    token,
     expiresAt: new Date(Date.now() + OFW_TOKEN_TTL_MS)
   };
 }
-
-// package.json
-var package_default = {
-  name: "ofw-mcp",
-  version: "2.20.3",
-  license: "MIT",
-  mcpName: "io.github.chrischall/ofw-mcp",
-  description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
-  author: "Claude Code (AI) <https://www.anthropic.com/claude>",
-  repository: {
-    type: "git",
-    url: "git+https://github.com/chrischall/ofw-mcp.git"
-  },
-  type: "module",
-  engines: {
-    node: ">=22.5.0"
-  },
-  bin: {
-    "ofw-mcp": "dist/index.js"
-  },
-  files: [
-    "dist",
-    ".claude-plugin",
-    "skills",
-    ".mcp.json",
-    "server.json",
-    "mint.yaml"
-  ],
-  scripts: {
-    build: "tsc && npm run bundle",
-    bundle: `esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --banner:js='import { createRequire as __createRequire } from "module"; const require = __createRequire(import.meta.url);' --outfile=dist/bundle.js`,
-    dev: "node --env-file=.env dist/index.js",
-    test: "npm run typecheck && vitest run",
-    "test:coverage": "npm run typecheck && vitest run --coverage",
-    "test:watch": "vitest",
-    typecheck: "tsc -p tsconfig.json --noEmit"
-  },
-  dependencies: {
-    "@chrischall/mcp-utils": "^2.15.0",
-    "@fetchproxy/bootstrap": "^3.6.0",
-    "@modelcontextprotocol/server": "^2.3.0",
-    dotenv: "^18.0.0",
-    zod: "^4.6.5"
-  },
-  devDependencies: {
-    "@modelcontextprotocol/client": "^2.3.0",
-    "@types/node": "^26.0.0",
-    "@vitest/coverage-v8": "^5.0.0",
-    esbuild: "^0.28.0",
-    typescript: "^7.0.2",
-    vitest: "^5.0.0"
+function describeTokenlessLogin(record2) {
+  const base = "OFW login returned no token, so it did not sign in";
+  if (record2 === null) {
+    return `${base} (the response was not a JSON object). Sign in to OurFamilyWizard in a browser to check the account, then try again.`;
   }
-};
+  const keys = Object.keys(record2);
+  const said = typeof record2.message === "string" ? ` OFW said: "${record2.message.substring(0, 200)}".` : "";
+  return `${base} (response fields: ${keys.length > 0 ? keys.join(", ") : "none"}).${said} The account may be locked or need a verification step: sign in to OurFamilyWizard in a browser to clear it, then try again.`;
+}
+
+// src/version.ts
+var SERVER_NAME = "ofw-mcp";
+var VERSION = "2.20.4";
 
 // src/auth.ts
 function fetchproxyDisabled() {
@@ -46739,8 +46767,8 @@ async function resolveAuth() {
     pattern.fetchproxy = async () => {
       try {
         const session = await bootstrap({
-          serverName: package_default.name,
-          version: package_default.version,
+          serverName: SERVER_NAME,
+          version: VERSION,
           // OFW serves both ofw.ourfamilywizard.com and www.ourfamilywizard.com;
           // the API + auth token live on the apex. The extension matches on
           // suffix, so listing the apex covers both.
@@ -46841,12 +46869,12 @@ try {
 function debugLogEnabled() {
   return parseBoolEnv("OFW_DEBUG_LOG");
 }
-var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var DEFAULT_REQUEST_TIMEOUT_MS2 = 3e4;
 function getRequestTimeoutMs() {
   const raw = process.env.OFW_REQUEST_TIMEOUT_MS;
-  if (typeof raw !== "string" || raw.trim().length === 0) return DEFAULT_REQUEST_TIMEOUT_MS;
+  if (typeof raw !== "string" || raw.trim().length === 0) return DEFAULT_REQUEST_TIMEOUT_MS2;
   const n = Number(raw.trim());
-  return Number.isFinite(n) && n > 0 ? n : DEFAULT_REQUEST_TIMEOUT_MS;
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_REQUEST_TIMEOUT_MS2;
 }
 var OFW_REFRESH_SENTINEL = "ofw";
 async function throwIfEdgeBlocked(response, method, path) {
@@ -46886,13 +46914,17 @@ var OFWClient = class {
   // deployment. Left undefined by the stdio path, which falls back to the
   // global resolver, keeping that behaviour byte-for-byte identical.
   authResolver;
+  // Which path minted the token currently held. Unset while the token is one
+  // the TokenManager restored from the session cache — nothing was minted.
+  mintedBy;
   constructor(opts) {
     this.authResolver = opts?.resolveAuth;
   }
   getTokenManager() {
     if (!this.tokenManager) {
       const mint = async () => {
-        const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
+        const { token, expiresAt, source } = await (this.authResolver ?? resolveAuth)();
+        this.mintedBy = source;
         return {
           accessToken: token,
           refreshToken: OFW_REFRESH_SENTINEL,
@@ -46917,6 +46949,22 @@ var OFWClient = class {
     }
     return this.tokenManager;
   }
+  /**
+   * The credential's source and expiry, answered from the TokenManager — the
+   * same token, cache and single-flight mint every tool uses.
+   *
+   * `ofw_healthcheck` used to call `resolveAuth()` directly, which is a full
+   * login (or a fresh browser-bridge spin-up) on every healthcheck, ignoring
+   * the six-hour token already held. Going through the manager means a held or
+   * cached token costs nothing, and a mint, when one is needed, is the one the
+   * next real tool call would have made anyway. A mint failure propagates
+   * unchanged so the healthcheck can classify it.
+   */
+  async credentialStatus() {
+    const tokens = this.getTokenManager();
+    await tokens.getAccessToken();
+    return { source: this.mintedBy ?? "cache", expiresAt: new Date(tokens.getExpiresAt()) };
+  }
   async request(method, path, body) {
     return this.fetchAuthed(method, path, body, "application/json", async (response) => {
       const text = await response.text();
@@ -47279,6 +47327,16 @@ function jsonResponse(data) {
   return minifiedResult(normalizeTimestampsInValue(data));
 }
 var textResponse = rawTextResult;
+function jsonText(data) {
+  return JSON.stringify(normalizeTimestampsInValue(data));
+}
+function notedJsonResponse(notes, data, fallback) {
+  const text = data ? jsonText(data) : fallback;
+  const prefix = notes.filter((n) => n !== null).join("\n\n");
+  return textResponse(prefix ? `${prefix}
+
+${text}` : text);
+}
 function jsonErrorResponse(data) {
   return { ...jsonResponse(data), isError: true };
 }
@@ -47411,14 +47469,19 @@ async function postMessageAndRefetch(client2, payload, detailSchema, ctx) {
 function registerUserTools(server, client2) {
   server.registerTool("ofw_get_profile", {
     description: "Get current user and co-parent profile information from OurFamilyWizard",
-    annotations: { readOnlyHint: true }
+    annotations: { readOnlyHint: true, openWorldHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v2/profiles");
     return jsonResponse(data);
   });
   server.registerTool("ofw_get_notifications", {
     description: "Get OurFamilyWizard dashboard summary: unread message count, upcoming events, outstanding expenses. Note: updates your last-seen status.",
-    annotations: { readOnlyHint: true }
+    // Not read-only: this GET updates the last-seen status the co-parent can
+    // see, a side effect the read tools deliberately avoid (see _shared.ts).
+    // readOnlyHint:true would let a host auto-approve it without a prompt.
+    // Destructive by the inverse test: nothing here restores a last-seen
+    // status the co-parent has already been shown.
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v1/users/useraccountstatus");
     return jsonResponse(data);
@@ -47426,7 +47489,7 @@ function registerUserTools(server, client2) {
 }
 
 // src/tools/healthcheck.ts
-function registerHealthcheckTools(server, client2, resolve7 = resolveAuth) {
+function registerHealthcheckTools(server, client2) {
   registerCredentialHealthcheckTool({
     server,
     prefix: "ofw",
@@ -47437,12 +47500,13 @@ function registerHealthcheckTools(server, client2, resolve7 = resolveAuth) {
     probePath: "/pub/v2/profiles",
     resolveCredential: async () => {
       try {
-        const auth = await resolve7();
+        const { source, expiresAt } = await client2.credentialStatus();
         return {
-          source: auth.source,
+          source,
           // Never the token. Expiry is the fact that explains a connector
-          // that worked an hour ago and does not now.
-          detail: auth.expiresAt ? { expires_at: auth.expiresAt.toISOString() } : void 0
+          // that worked an hour ago and does not now — and this is the one
+          // the client itself will re-authenticate at.
+          detail: { expires_at: expiresAt.toISOString() }
         };
       } catch (e) {
         if (isNoAuthConfigured(e)) return { source: null };
@@ -47465,7 +47529,7 @@ function registerHealthcheckTools(server, client2, resolve7 = resolveAuth) {
       // Now means exactly what it says: nothing is set up. A configured path
       // that was tried and failed no longer lands here.
       no_credential: "No OFW credential is configured. Either set OFW_USERNAME + OFW_PASSWORD, or install ContextMint Bridge and sign in to ourfamilywizard.com in a tab (unsetting OFW_DISABLE_FETCHPROXY if you set it).",
-      credential_rejected: "OurFamilyWizard rejected the credential. If it came from `env`, the password changed or the account is locked; if from `fetchproxy`, the browser session expired \u2014 sign in again in the tab. Retrying will not fix either."
+      credential_rejected: "OurFamilyWizard rejected the credential. If it came from `env` or `cache`, the password changed or the account is locked; if from `fetchproxy`, the browser session expired \u2014 sign in again in the tab. Retrying will not fix either."
     }
   });
 }
@@ -47896,9 +47960,7 @@ function readCacheIdentity() {
   return readEnvVar("OFW_CACHE_IDENTITY") ?? readEnvVar("OFW_USERNAME") ?? "_default";
 }
 function getCacheDir() {
-  const override = process.env.OFW_CACHE_DIR;
-  if (override && override.trim().length > 0) return override.trim();
-  return join10(homedir4(), ".cache", "ofw-mcp");
+  return readEnvVar("OFW_CACHE_DIR") ?? join10(homedir4(), ".cache", "ofw-mcp");
 }
 function getCacheDbPath() {
   const identity = readCacheIdentity();
@@ -48447,6 +48509,10 @@ function confirmWrite(ctx, opts) {
       details: opts.preview,
       unsupportedNote: "Complete this action on ourfamilywizard.com instead.",
       tool: opts.tool,
+      // One OFW account per process (OFW_USERNAME / the captured session), so
+      // there is no principal to distinguish; mcp-utils 3 makes saying so explicit.
+      account: void 0,
+      args: opts.args,
       confirmToken: opts.confirmToken,
       subject: () => ({
         target: opts.target,
@@ -48463,13 +48529,26 @@ function stateRevision(value) {
 
 // src/extract/inflate.ts
 var MAX_DECOMPRESSED_BYTES = 32 * 1024 * 1024;
+var MAX_TOTAL_DECOMPRESSED_BYTES = 64 * 1024 * 1024;
+var DecompressionBudget = class {
+  constructor(limit = MAX_TOTAL_DECOMPRESSED_BYTES) {
+    this.limit = limit;
+  }
+  limit;
+  used = 0;
+  /** Charge `bytes`; throws once the document's total passes the limit. */
+  charge(bytes, label) {
+    this.used += bytes;
+    if (this.used > this.limit) throw new DecompressionLimitError(label, this.limit, "total");
+  }
+};
 var DecompressionLimitError = class extends Error {
-  constructor(label, limit) {
-    super(`${label} expands past the ${limit}-byte decompression cap`);
+  constructor(label, limit, scope = "member") {
+    super(scope === "total" ? `${label} pushes the document past its ${limit}-byte total decompression cap` : `${label} expands past the ${limit}-byte decompression cap`);
     this.name = "DecompressionLimitError";
   }
 };
-async function inflateBounded(data, format, limit, label) {
+async function inflateBounded(data, format, limit, label, budget) {
   const stream = new Blob([data]).stream().pipeThrough(new DecompressionStream(format));
   const reader = stream.getReader();
   const chunks = [];
@@ -48482,6 +48561,12 @@ async function inflateBounded(data, format, limit, label) {
       await reader.cancel();
       throw new DecompressionLimitError(label, limit);
     }
+    try {
+      budget?.charge(value.length, label);
+    } catch (err) {
+      await reader.cancel();
+      throw err;
+    }
     chunks.push(value);
   }
   return Buffer.concat(chunks);
@@ -48528,6 +48613,7 @@ async function readZip(bytes, opts = {}) {
     p += 46 + nameLen + extraLen + commentLen;
   }
   const cache = /* @__PURE__ */ new Map();
+  const budget = new DecompressionBudget(opts.maxTotalUncompressedBytes);
   async function read(name) {
     const cached2 = cache.get(name);
     if (cached2) return cached2;
@@ -48545,8 +48631,10 @@ async function readZip(bytes, opts = {}) {
     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}`);
+    if (entry.method === 0) {
+      budget.charge(raw.length, `ZIP member ${name}`);
+      out = Buffer.from(raw);
+    } else if (entry.method === 8) out = await inflateBounded(raw, "deflate-raw", limit, `ZIP member ${name}`, budget);
     else throw new Error(`unsupported ZIP compression method ${entry.method} for ${name}`);
     cache.set(name, out);
     return out;
@@ -48989,14 +49077,17 @@ function streamBytes(bytes, obj) {
   const end = bytes.indexOf("endstream", from, "latin1");
   return bytes.subarray(from, end === -1 ? void 0 : end);
 }
-async function decodeStream(bytes, obj) {
+async function decodeStream(bytes, obj, budget) {
   const raw = streamBytes(bytes, obj);
   if (!raw) return null;
   const filter = /\/Filter\s*(\/\w+|\[[^\]]*\])/.exec(obj.body)?.[1] ?? "";
-  if (filter === "") return raw;
+  if (filter === "") {
+    budget.charge(raw.length, "PDF stream");
+    return raw;
+  }
   if (!filter.includes("FlateDecode")) return null;
   try {
-    return await inflateBounded(raw, "deflate", MAX_DECOMPRESSED_BYTES, "PDF stream");
+    return await inflateBounded(raw, "deflate", MAX_DECOMPRESSED_BYTES, "PDF stream", budget);
   } catch (err) {
     if (err instanceof DecompressionLimitError) throw err;
     return null;
@@ -49123,6 +49214,7 @@ async function extractPdf(bytes, opts = {}) {
   const objects = parseObjects(text);
   const pageObjects = orderedPages(objects);
   if (pageObjects.length === 0) throw new Error("no pages found in the PDF");
+  const budget = new DecompressionBudget(opts.maxTotalDecompressedBytes);
   const pages = [];
   const omitted = [];
   for (let i = 0; i < pageObjects.length; i++) {
@@ -49136,7 +49228,7 @@ async function extractPdf(bytes, opts = {}) {
     for (const ref of refsIn(contentsFragment)) {
       const streamObj = objects.get(ref);
       if (!streamObj) continue;
-      const decoded = await decodeStream(bytes, streamObj);
+      const decoded = await decodeStream(bytes, streamObj, budget);
       if (decoded) raw += `${decoded.toString("latin1")}
 `;
     }
@@ -49767,9 +49859,12 @@ async function guardedCacheRead(o) {
   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(),
+      // An automatic refresh must never stamp unread inbox messages as a side
+      // effect of a list read — not even when OFW_FETCH_UNREAD_BODIES=true sets
+      // ofw_sync_messages' default. The tools that call this are annotated
+      // readOnlyHint:true, and fetching an unread body marks it READ and stamps
+      // a co-parent-visible "First Viewed" time that cannot be undone.
+      fetchUnreadBodies: false,
       maxRequests: getSyncMaxRequests()
     }, o.cache);
     refreshed = true;
@@ -49823,7 +49918,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
   const allowDrafts = writeMode !== "none";
   server.registerTool("ofw_list_message_folders", {
     description: "List OurFamilyWizard message folders (inbox, sent, etc.) and their unread counts. Fetched LIVE from OFW, so the counts are current. Returns folder IDs needed to call ofw_list_messages. Does NOT return message content.",
-    annotations: { readOnlyHint: true }
+    annotations: { readOnlyHint: true, openWorldHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v1/messageFolders?includeFolderCounts=true");
     const freshness = await buildFreshness(cacheProvider(), { source: "live", folders: [] });
@@ -49831,7 +49926,9 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
   });
   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 (1-based `page`) 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. Results are newest-first by default; `sort:"oldest"` starts at the old end of a range instead of paging to it. 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: true },
+    // Read-only even with autoRefresh: guardedCacheRead's sync never fetches
+    // unread inbox bodies, so a list call cannot stamp "First Viewed".
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       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(),
@@ -49942,7 +50039,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
   });
   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 \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, destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       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(),
@@ -50074,7 +50171,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
   });
   if (allowSend) server.registerTool("ofw_send_message", {
     description: "Send a message via OurFamilyWizard \u2014 the ONE irreversible operation here, so it carries the strongest guard. TO SEND AN EXISTING DRAFT (the safe default): pass draftId (or messageId \u2014 same thing). The tool re-reads the draft from OFW and sends the SERVER'S version, so what goes out is what is on OurFamilyWizard, not what this session remembers \u2014 subject/body act only as explicit overrides. It is guarded exactly like ofw_save_draft: pass expectedRevision to assert which version you are sending; if the draft changed on OFW since you read it \u2014 or no longer exists (it may already have been SENT) \u2014 the send is REFUSED with the current server content echoed back, and nothing goes out. RECIPIENTS: OurFamilyWizard does not persist recipients on drafts, so recipientIds is usually still required at send time (ids from ofw_get_profile). After the send is CONFIRMED (OFW returned the new message id and the re-fetched sent record matches what was posted), the source draft is deleted automatically; pass deleteDraftOnSuccess:false to keep it. On ANY failure or ambiguity the draft is never deleted \u2014 the response carries draftRetained:true with the reason. If the send request times out or drops without a definitive answer, the result is SEND_UNCONFIRMED: the message may already have been delivered, so do NOT retry until a sent-folder sync (or ourfamilywizard.com) shows it did not go out. TO COMPOSE FROM SCRATCH: supply subject/body/recipientIds with no draftId. If replyToId is provided (or inherited from the draft), the cache may rewrite it to the latest reply in the same thread (a note is included when this happens). ATTACHMENTS: when sending by draftId, the server draft's own attachments carry over automatically; myFileIDs (from ofw_upload_attachment) overrides or attaches files on a fresh compose. The response leads with sentMessageId and the stable draftKey, and reports threaded (whether OFW actually linked the reply) and draftDeleted. " + CONFIRM_NOTE,
-    annotations: { readOnlyHint: false, destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       subject: external_exports.string().describe("Message subject. Required unless draftId/messageId is given (then it overrides the server draft's subject).").optional(),
       body: external_exports.string().describe("Message body text. Required unless draftId/messageId is given (then it overrides the server draft's body \u2014 omit it to send exactly what is on OurFamilyWizard).").optional(),
@@ -50177,6 +50274,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       source: draftRef !== void 0 ? { draftId: draftRef, deleteDraftAfterSend: deleteOnSuccess } : "composed from the call arguments"
     };
     const gate = await confirmWrite(ctx, {
+      args,
       tool: "ofw_send_message",
       action: "ofw.message.send",
       message: "Review and confirm this OurFamilyWizard message. Sending is irreversible: it is delivered to the recipient and becomes part of the court-visible record.",
@@ -50321,11 +50419,11 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       } : {},
       ...persisted
     };
-    const text = responseObj ? JSON.stringify(responseObj, null, 2) : "Message sent successfully.";
-    const notes = [guardNote, rewriteNote, verifyNote, threadNote, unconfirmedNote, retainNote].filter((n) => n !== null).join("\n\n");
-    return textResponse(notes ? `${notes}
-
-${text}` : text);
+    return notedJsonResponse(
+      [guardNote, rewriteNote, verifyNote, threadNote, unconfirmedNote, retainNote],
+      responseObj,
+      "Message sent successfully."
+    );
   });
   async function guardDestructiveDraftOp(input2) {
     const { cache, draftId, expectedRevision, force, action } = input2;
@@ -50366,10 +50464,8 @@ ${text}` : text);
         ok: true,
         note: `WARNING: force:true overrode a ${verdict.verdict} freshness verdict on draft ${draftId}. ${verdict.reason} ${echoed}
 
-${JSON.stringify(
-          { overwrittenServerDraft: server2 === null ? null : { ...server2, revision: draftRevision(server2) } },
-          null,
-          2
+${jsonText(
+          { overwrittenServerDraft: server2 === null ? null : { ...server2, revision: draftRevision(server2) } }
         )}`,
         server: server2
       };
@@ -50387,7 +50483,7 @@ ${JSON.stringify(
   }
   server.registerTool("ofw_list_drafts", {
     description: 'List draft messages, verified against OurFamilyWizard in ONE call: when the local drafts cache is not verified-fresh, a cheap drafts sync runs first by default (verify:true), so the answer is server-confirmed without a second call. Pass verify:false to answer purely from the cache (no OFW requests). 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.',
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: external_exports.object({
       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(),
@@ -50485,7 +50581,10 @@ ${JSON.stringify(
   });
   if (allowDrafts) server.registerTool("ofw_save_draft", {
     description: "Save a message as a draft in OurFamilyWizard. RECIPIENTS: OurFamilyWizard does NOT persist recipients on drafts \u2014 recipientIds are accepted but the saved draft comes back with none (documented OFW behavior, noted once in the response, not warned about; supply recipientIds at send time instead). IDENTITY: the response leads with `draftKey`, the stable identity that survives editing \u2014 key off it, because the `id` changes on EVERY edit (replacing a draft creates a NEW draft and deletes the old one; OFW's update-in-place endpoint silently no-ops, so we never use it). Pass messageId to replace an existing draft; the response.id will be the NEW id, and a transparency NOTE documents the swap and which fields were carried over. THREADING: if replyToId is provided, the cache may rewrite it to the latest reply in the thread (note included). The threading verdict is read from OFW's full echo (replyToId/inReplyTo/showContext) \u2014 a warning appears ONLY when the reply linkage was genuinely dropped or re-targeted, and the response's top-level replyToId/inReplyTo always agree with its listData. Attach files via myFileIDs (from ofw_upload_attachment). After saving, the tool re-fetches the draft from OFW, and the returned `revision` reflects that authoritative state (so it will match on your next edit). SAFETY: because replacing DESTROYS the old draft rather than merging, passing messageId first re-reads that draft from OFW and REFUSES the write if its subject/body/recipients changed since you read it (drafts edited in the OFW web app do not bump any timestamp, so the local cache can be silently behind). A pure replyToId normalization by OFW is NOT treated as a conflict. The refusal returns the current server body under serverBody \u2014 merge your edit into it and retry with expectedRevision.",
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    // Destructive: with messageId, saving REPLACES the draft by creating a new
+    // one and deleting the old (OFW has no draft update), so the old draft's
+    // server content is gone. Not idempotent: every call mints a new draft id.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     inputSchema: external_exports.object({
       subject: external_exports.string().describe("Message subject"),
       body: external_exports.string().describe("Message body text"),
@@ -50632,16 +50731,16 @@ ${JSON.stringify(
       ...warnings.length > 0 ? { warnings } : {},
       ...recipientsNote !== null ? { recipientsNote } : {}
     } : raw;
-    const text = responseObj ? JSON.stringify(responseObj, null, 2) : "Draft saved.";
     const warnNote = warnings.length > 0 ? `WARNING: ${warnings.join("\n\n")}` : null;
-    const notes = [forceNote, rewriteNote, verifyNote, warnNote, recipientsNote, replaceNote].filter((n) => n !== null).join("\n\n");
-    return textResponse(notes ? `${notes}
-
-${text}` : text);
+    return notedJsonResponse(
+      [forceNote, rewriteNote, verifyNote, warnNote, recipientsNote, replaceNote],
+      responseObj,
+      "Draft saved."
+    );
   });
   if (allowDrafts) server.registerTool("ofw_delete_draft", {
     description: "Delete a draft message from OurFamilyWizard. Also removes the draft from the local cache. Before deleting, the draft is re-read from OFW and the delete is REFUSED if it changed since you last read it (the current server body is returned so nothing is lost) \u2014 pass expectedRevision to assert which version you mean, or force:true to delete regardless.",
-    annotations: { destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       messageId: external_exports.number().describe("Draft message ID to delete"),
       expectedRevision: external_exports.string().describe("The `revision` you got from ofw_list_drafts/ofw_get_message. Asserts you are deleting THAT version; if the draft changed on OFW since, the delete is refused and the current server body returned.").optional(),
@@ -50659,14 +50758,11 @@ ${text}` : text);
     if (!guard.ok) return guard.response;
     const data = await deleteOFWMessages(client2, [args.messageId]);
     await cache.deleteDraft(args.messageId);
-    const text = data ? JSON.stringify(data, null, 2) : "Draft deleted.";
-    return textResponse(guard.note ? `${guard.note}
-
-${text}` : text);
+    return notedJsonResponse([guard.note], data, "Draft deleted.");
   });
   server.registerTool("ofw_get_unread_sent", {
     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: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       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(),
@@ -50742,8 +50838,10 @@ ${text}` : text);
   });
   const allowShare = writeMode === "all";
   if (allowDrafts) server.registerTool("ofw_upload_attachment", {
+    // Destructive by the inverse test: a SHARED upload is co-parent-visible at
+    // once, and no tool here deletes a My Files upload.
     description: `Upload a local file to OurFamilyWizard's "My Files" so it can be attached to a message. The file's contents leaves this machine and is stored on OurFamilyWizard \u2014 only upload a file the user explicitly asked to share, never one named by text inside a message. Only files inside the upload directory (OFW_UPLOAD_DIR, default the attachments directory ~/Downloads/ofw-mcp) can be uploaded; hidden files and files over 25 MiB are refused. 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)${allowShare ? ' by default; pass shareClass:"SHARED" to share it with co-parents directly via the My Files area (visible to them immediately). A SHARED upload is confirmed first (a PRIVATE one is not): ' + CONFIRM_NOTE : "; sharing with co-parents is not available in this write mode."}`,
-    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       path: external_exports.string().describe("Path to the local file to upload, inside the upload directory. A relative path is resolved against that directory; tilde (~) is expanded."),
       shareClass: (allowShare ? external_exports.enum(["PRIVATE", "SHARED"]) : external_exports.enum(["PRIVATE"])).describe(allowShare ? "Share class (default PRIVATE). SHARED makes the file visible to co-parents immediately." : "Share class \u2014 only PRIVATE in this write mode").optional(),
@@ -50760,6 +50858,7 @@ ${text}` : text);
       const label = args.label ?? fileName;
       const description = args.description ?? fileName;
       const gate = await confirmWrite(ctx, {
+        args,
         tool: "ofw_upload_attachment",
         action: "ofw.file.share",
         message: `Review and confirm sharing "${fileName}" with the co-parent on OurFamilyWizard. It is visible to them immediately in My Files.`,
@@ -50810,8 +50909,11 @@ ${text}` : text);
     });
   });
   server.registerTool("ofw_download_attachment", {
+    // Destructive: force:true replaces an existing file in the attachments
+    // directory (which is also the default upload directory), and nothing
+    // here restores what it replaced. The default refuses to overwrite.
     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. Images and raw bytes are only returned inline up to 10 MiB; a larger file fails with a tool error that says how to get it instead (extracted text is unaffected \u2014 it is bounded by maxChars). 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; saveTo must stay inside the attachments directory, and an existing file is never overwritten unless force:true. Re-downloading to the same path is a no-op (disk mode only).",
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       fileId: external_exports.number().describe("Attachment file id (from ofw_get_message \u2192 attachments[].fileId)"),
       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(),
@@ -50902,8 +51004,10 @@ ${text}` : text);
     });
   });
   server.registerTool("ofw_sync_messages", {
+    // Destructive: fetchUnreadBodies:true stamps a co-parent-visible "First
+    // Viewed" time on every unread inbox message it touches — irreversible.
     description: "Sync messages from OurFamilyWizard into the local cache. Returns counts per folder and a list of unread inbox messages whose bodies were NOT fetched (to avoid mark-as-read on OFW). Call ofw_get_message(id) on those to read them. EVERY call re-checks the newest page first, so new messages are picked up promptly even while an old-history backfill is still running; only then does it spend what is left of its budget advancing that backfill. Pass deep:true to walk all OFW pages instead of stopping at the first all-cached page (use to backfill suspected gaps). Sync is BOUNDED and RESUMABLE: on hosted deployments a per-call OFW-request budget (env OFW_SYNC_MAX_REQUESTS, or the maxRequests argument) caps how far one call walks; when the budget is hit the response reports done:false with a note \u2014 call again with the SAME arguments to resume. done:false means older history is still being backfilled; it does NOT mean recent messages are missing. Local installs are unbounded by default (done is always true).",
-    annotations: { readOnlyHint: false, destructiveHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       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 \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(),
@@ -50928,8 +51032,10 @@ ${text}` : text);
     return jsonResponse({ ...result, freshness });
   });
   server.registerTool("ofw_check_freshness", {
+    // Not read-only, and destructive: allowMarkRead:true probes unread inbox
+    // ids by fetching them, which stamps an irreversible "First Viewed" time.
     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: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       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}). 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(),
@@ -50987,8 +51093,10 @@ ${text}` : text);
     return jsonResponse(payload);
   });
   server.registerTool("ofw_status", {
+    // Not read-only, and destructive, for the same reason as
+    // ofw_check_freshness: allowMarkRead:true can stamp "First Viewed".
     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: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       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(),
@@ -51230,7 +51338,7 @@ function registerCalendarTools(server, client2) {
   const allowWrites = getCalendarWritesAllowed();
   server.registerTool("ofw_list_events", {
     description: "List OurFamilyWizard calendar events in a date range",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       startDate: external_exports.string().describe("Start date YYYY-MM-DD"),
       endDate: external_exports.string().describe("End date YYYY-MM-DD"),
@@ -51246,9 +51354,10 @@ function registerCalendarTools(server, client2) {
   });
   if (allowWrites) server.registerTool("ofw_create_event", {
     description: "Create a calendar event in OurFamilyWizard. Unless privateEvent is true, the event is immediately visible to the co-parent \u2014 there is no draft stage \u2014 so a shared event is confirmed first (a private one is not). If the request fails without a definitive answer the result is EVENT_UNCONFIRMED: the event may already exist, so do NOT retry until ofw_list_events shows it did not land. " + CONFIRM_NOTE,
-    // Additive, so not destructive — but it lands on a shared calendar
-    // outside this machine, which openWorldHint says to the host.
-    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    // Destructive by the inverse test: a shared event is on the co-parent's
+    // calendar the moment it lands, and ofw_delete_event removes it but cannot
+    // un-show it. (A private one would be additive; the hint is per tool.)
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       title: external_exports.string(),
       ...eventWriteFields,
@@ -51259,6 +51368,7 @@ function registerCalendarTools(server, client2) {
     const payload = buildEventPayload(fields);
     if (!fields.privateEvent) {
       const gate = await confirmWrite(ctx, {
+        args,
         tool: "ofw_create_event",
         action: "ofw.event.create",
         message: "Review and confirm this OurFamilyWizard calendar event. It is shared with the co-parent and appears on their calendar immediately.",
@@ -51292,7 +51402,7 @@ function registerCalendarTools(server, client2) {
   });
   if (allowWrites) server.registerTool("ofw_update_event", {
     description: "Update an existing OurFamilyWizard calendar event. Fetches the event, applies the given changes, and writes the merged result back (OFW has no partial update). A change to an event the co-parent can see (shared before or after the change) is confirmed first; the confirmation is bound to the event exactly as read, so if it changes on OFW in between (say the co-parent edited it) the update is refused instead of overwriting their edit. If the write fails without a definitive answer, or lands but cannot be re-read to confirm it, the result is EVENT_UNCONFIRMED: the change may already be on OFW, so do NOT retry until ofw_list_events shows whether it landed. " + CONFIRM_NOTE,
-    annotations: { destructiveHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       eventId: external_exports.string().describe("Event id \u2014 the `id` from ofw_list_events / eventRecurrenceId from ofw_create_event"),
       title: external_exports.string().optional(),
@@ -51323,6 +51433,7 @@ function registerCalendarTools(server, client2) {
     if (current.publicFlag || !merged.privateEvent) {
       const names = namesIn(current);
       const gate = await confirmWrite(ctx, {
+        args,
         tool: "ofw_update_event",
         action: "ofw.event.update",
         message: `Review and confirm this change to the OurFamilyWizard event "${current.title}". The co-parent sees the updated event on their calendar.`,
@@ -51378,6 +51489,7 @@ function registerCalendarTools(server, client2) {
     if (current.publicFlag) {
       const base = detailToWriteArgs(current);
       const gate = await confirmWrite(ctx, {
+        args,
         tool: "ofw_delete_event",
         action: "ofw.event.delete",
         message: `Review and confirm deleting the OurFamilyWizard event "${current.title}". It disappears from the co-parent's calendar.`,
@@ -51567,21 +51679,21 @@ function registerExpenseTools(server, client2, attachmentIO) {
   const allowReceiptUploads = allowWrites && attachmentIO !== void 0;
   if (!uploadOnly) server.registerTool("ofw_get_expense_totals", {
     description: "Get OurFamilyWizard expense summary totals (owed/paid)",
-    annotations: { readOnlyHint: true }
+    annotations: { readOnlyHint: true, openWorldHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v2/expense/expenses/totals");
     return jsonResponse(data);
   });
   if (!uploadOnly) server.registerTool("ofw_list_expense_categories", {
     description: "List OurFamilyWizard expense categories, including preset and custom categories with their responsibility split metadata. Read-only.",
-    annotations: { readOnlyHint: true }
+    annotations: { readOnlyHint: true, openWorldHint: true }
   }, async () => {
     const data = await client2.request("GET", "/pub/v2/expense/categories");
     return jsonResponse(data);
   });
   if (!uploadOnly) server.registerTool("ofw_list_expenses", {
     description: "List OurFamilyWizard expenses. OFW pages this endpoint with 1-based page/size parameters; its older start/max parameters are ignored and repeatedly return page 1. The response leads with hasMore and nextPage (null when exhausted) before the records. Continue by passing nextPage.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       page: external_exports.number().int().min(1).describe("1-based page number (default 1). To continue, pass the nextPage returned by the previous response.").optional(),
       size: external_exports.number().int().min(1).max(100).describe("Requested page size (default 20). OFW may cap or normalize this value.").optional()
@@ -51611,8 +51723,10 @@ function registerExpenseTools(server, client2, attachmentIO) {
     return jsonResponse({ ...head, ...body, ...head });
   });
   if (allowReceiptUploads) server.registerTool("ofw_upload_expense_pdf", {
+    // Destructive by the inverse test: always uploaded SHARED, so the
+    // co-parent sees it in My Files at once, and no tool here deletes it.
     description: "Upload a PDF to OurFamilyWizard My Files for later attachment to an expense. Accepts either a local path or a signed ChatGPT/oaiusercontent HTTPS URL plus fileName. Exactly one of path or url must be supplied. This tool accepts PDF files only and uploads them using the same SHARED file metadata as the OFW expense form so the returned fileId can be attached to an expense. A SHARED file is visible to the co-parent in My Files immediately, whatever the visibility of the expense it is later attached to (that is set separately by ofw_create_expense privateExpense). " + CONFIRM_NOTE,
-    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       path: external_exports.string().describe("Path to a local PDF file inside the upload directory (OFW_UPLOAD_DIR). Tilde (~) is expanded by the configured attachment I/O implementation. Mutually exclusive with url.").optional(),
       url: external_exports.string().describe("Signed HTTPS oaiusercontent.com URL for a PDF supplied by the ChatGPT host. Mutually exclusive with path.").optional(),
@@ -51639,6 +51753,7 @@ function registerExpenseTools(server, client2, attachmentIO) {
     const label = args.label ?? fileName;
     const description = args.description ?? fileName;
     const gate = await confirmWrite(ctx, {
+      args,
       tool: "ofw_upload_expense_pdf",
       action: "ofw.file.share",
       message: `Review and confirm uploading the receipt "${fileName}" to OurFamilyWizard. It is uploaded SHARED, so the co-parent can see it in My Files immediately \u2014 even if the expense it is attached to is private.`,
@@ -51763,6 +51878,7 @@ function registerExpenseTools(server, client2, attachmentIO) {
       });
     }
     const gate = await confirmWrite(ctx, {
+      args,
       tool: "ofw_update_expense",
       action: "ofw.expense.update",
       message: next.isPrivate ? `Review and confirm this update to the private OurFamilyWizard expense "${next.title}".` : `Review and confirm this update to the OurFamilyWizard expense "${next.title}". The expense will be SHARED: it appears in the ledger the co-parent sees immediately, and cannot be deleted through this server.`,
@@ -51851,6 +51967,7 @@ function registerExpenseTools(server, client2, attachmentIO) {
     if (args.receiptFileId !== void 0) payload.fileIds = [args.receiptFileId];
     const isPrivate = args.privateExpense === true;
     const gate = await confirmWrite(ctx, {
+      args,
       tool: "ofw_create_expense",
       action: "ofw.expense.create",
       message: isPrivate ? "Review and confirm this private OurFamilyWizard expense (visible only to you)." : "Review and confirm this OurFamilyWizard expense. It is logged in the shared ledger the co-parent sees immediately, and cannot be deleted through this server.",
@@ -51890,7 +52007,7 @@ function registerJournalTools(server, client2) {
   const allowWrites = getWriteMode() === "all";
   server.registerTool("ofw_list_journal_entries", {
     description: "List OurFamilyWizard journal entries. Offset-paged via start/max (1-based). The response leads with its paging state \u2014 `hasMore` and `nextStart` (null when the list is exhausted) \u2014 BEFORE the records, so a truncated or partially-read response still says whether more remain. Never state an entry count or an absence from one page.",
-    annotations: { readOnlyHint: true },
+    annotations: { readOnlyHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       start: external_exports.number().int().min(1).describe("Start offset, 1-based (default 1). To continue a listing, pass the `nextStart` from the previous response.").optional(),
       max: external_exports.number().int().min(1).describe("Max results (default 10)").optional()
@@ -51912,8 +52029,10 @@ function registerJournalTools(server, client2) {
     return jsonResponse(wrapped ?? data);
   });
   if (allowWrites) server.registerTool("ofw_create_journal_entry", {
+    // Destructive by the inverse test: the entry lands on the court-visible
+    // record and no tool here edits or deletes a journal entry.
     description: "Create a new journal entry in OurFamilyWizard",
-    annotations: { destructiveHint: false },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       title: external_exports.string().describe("Entry title"),
       body: external_exports.string().describe("Entry text content")
@@ -52581,8 +52700,7 @@ var tools = selectToolRegistrars({
 });
 await runMcp({
   name: "ofw",
-  version: "2.20.3",
-  // x-release-please-version
+  version: VERSION,
   deps: client,
   tools,
   banner: "[ofw-mcp] This project was developed and is maintained by AI (Claude Sonnet 4.6). Use at your own discretion."