ofw-mcp 2.10.2 → 2.12.0

package/dist/bundle.js

@@ -2991,7 +2991,7 @@ var require_compile = __commonJS({
       const schOrFunc = root.refs[ref];
       if (schOrFunc)
         return schOrFunc;
-      let _sch = resolve2.call(this, root, ref);
+      let _sch = resolve3.call(this, root, ref);
       if (_sch === void 0) {
         const schema = (_a3 = root.localRefs) === null || _a3 === void 0 ? void 0 : _a3[ref];
         const { schemaId } = this.opts;
@@ -3018,7 +3018,7 @@ var require_compile = __commonJS({
     function sameSchemaEnv(s1, s2) {
       return s1.schema === s2.schema && s1.root === s2.root && s1.baseId === s2.baseId;
     }
-    function resolve2(root, ref) {
+    function resolve3(root, ref) {
       let sch;
       while (typeof (sch = this.refs[ref]) == "string")
         ref = sch;
@@ -3649,7 +3649,7 @@ var require_fast_uri = __commonJS({
       }
       return uri;
     }
-    function resolve2(baseURI, relativeURI, options) {
+    function resolve3(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
       const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
       const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
@@ -3933,7 +3933,7 @@ var require_fast_uri = __commonJS({
     var fastUri = {
       SCHEMES,
       normalize,
-      resolve: resolve2,
+      resolve: resolve3,
       resolveComponent,
       equal,
       serialize,
@@ -9161,7 +9161,7 @@ var require_websocket = __commonJS({
     var http = __require("http");
     var net = __require("net");
     var tls = __require("tls");
-    var { randomBytes, createHash: createHash2 } = __require("crypto");
+    var { randomBytes: randomBytes2, createHash: createHash2 } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -9699,7 +9699,7 @@ var require_websocket = __commonJS({
         }
       }
       const defaultPort = isSecure ? 443 : 80;
-      const key = randomBytes(16).toString("base64");
+      const key = randomBytes2(16).toString("base64");
       const request = isSecure ? https.request : http.request;
       const protocolSet = /* @__PURE__ */ new Set();
       let perMessageDeflate;
@@ -32550,7 +32550,7 @@ var Protocol = class {
           return;
         }
         const pollInterval = task2.pollInterval ?? this._options?.defaultTaskPollInterval ?? 1e3;
-        await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+        await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
         options?.signal?.throwIfAborted();
       }
     } catch (error51) {
@@ -32567,7 +32567,7 @@ var Protocol = class {
    */
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken, task, relatedTask } = options ?? {};
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       const earlyReject = (error51) => {
         reject(error51);
       };
@@ -32645,7 +32645,7 @@ var Protocol = class {
           if (!parseResult.success) {
             reject(parseResult.error);
           } else {
-            resolve2(parseResult.data);
+            resolve3(parseResult.data);
           }
         } catch (error51) {
           reject(error51);
@@ -32906,12 +32906,12 @@ var Protocol = class {
       }
     } catch {
     }
-    return new Promise((resolve2, reject) => {
+    return new Promise((resolve3, reject) => {
       if (signal.aborted) {
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
         return;
       }
-      const timeoutId = setTimeout(resolve2, interval);
+      const timeoutId = setTimeout(resolve3, interval);
       signal.addEventListener("abort", () => {
         clearTimeout(timeoutId);
         reject(new McpError(ErrorCode.InvalidRequest, "Request cancelled"));
@@ -34002,7 +34002,7 @@ var McpServer = class {
     let task = createTaskResult.task;
     const pollInterval = task.pollInterval ?? 5e3;
     while (task.status !== "completed" && task.status !== "failed" && task.status !== "cancelled") {
-      await new Promise((resolve2) => setTimeout(resolve2, pollInterval));
+      await new Promise((resolve3) => setTimeout(resolve3, pollInterval));
       const updatedTask = await extra.taskStore.getTask(taskId);
       if (!updatedTask) {
         throw new McpError(ErrorCode.InternalError, `Task ${taskId} not found during polling`);
@@ -34666,64 +34666,17 @@ var StdioServerTransport = class {
     this.onclose?.();
   }
   send(message) {
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const json2 = serializeMessage(message);
       if (this._stdout.write(json2)) {
-        resolve2();
+        resolve3();
       } else {
-        this._stdout.once("drain", resolve2);
+        this._stdout.once("drain", resolve3);
       }
     });
   }
 };
 
-// node_modules/@chrischall/mcp-utils/dist/server/index.js
-async function createMcpServer(opts) {
-  const server = new McpServer({ name: opts.name, version: opts.version });
-  if (opts.banner !== void 0) {
-    console.error(opts.banner);
-  }
-  const deps = opts.deps;
-  for (const register of opts.tools) {
-    await register(server, deps);
-  }
-  return server;
-}
-function withGracefulShutdown(server, opts = {}) {
-  const shouldExit = opts.exit ?? true;
-  let shuttingDown = false;
-  const handler = (signal) => {
-    if (shuttingDown)
-      return;
-    shuttingDown = true;
-    void (async () => {
-      try {
-        if (opts.onSignal)
-          await opts.onSignal(signal);
-        await server.close();
-      } catch (err) {
-        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
-      } finally {
-        if (shouldExit)
-          process.exit(0);
-      }
-    })();
-  };
-  process.on("SIGINT", () => handler("SIGINT"));
-  process.on("SIGTERM", () => handler("SIGTERM"));
-}
-async function runMcp(opts) {
-  const server = await createMcpServer(opts);
-  const shutdown = opts.shutdown ?? true;
-  if (shutdown !== false) {
-    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
-  }
-  const spec = opts.transport ?? "stdio";
-  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
-  await server.connect(transport);
-  return server;
-}
-
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
 var McpToolError = class extends Error {
   /** Actionable remediation text, when one applies. */
@@ -34736,6 +34689,9 @@ var McpToolError = class extends Error {
     Object.setPrototypeOf(this, new.target.prototype);
   }
 };
+function createHelpfulError(message, opts) {
+  return new McpToolError(message, opts);
+}
 var BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
 var JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,}\b/g;
 var BASIC_AUTH_RE = /(authorization\s*:\s*basic\s+)[A-Za-z0-9+/=_-]{6,}/gi;
@@ -34773,6 +34729,81 @@ function textResult(data) {
 function rawTextResult(text) {
   return { content: [{ type: "text", text }] };
 }
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: redactSecrets(message) }],
+    isError: true
+  };
+}
+
+// node_modules/@chrischall/mcp-utils/dist/server/index.js
+function hintResultOrRethrow(err) {
+  if (err instanceof McpToolError && err.hint) {
+    return errorResult(`${err.message}
+
+Hint: ${err.hint}`);
+  }
+  throw err;
+}
+function surfaceToolHints(server) {
+  const register = server.registerTool.bind(server);
+  server.registerTool = (name, config2, cb) => register(name, config2, (...args) => {
+    let result;
+    try {
+      result = cb(...args);
+    } catch (err) {
+      return hintResultOrRethrow(err);
+    }
+    return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
+  });
+}
+async function createMcpServer(opts) {
+  const server = new McpServer({ name: opts.name, version: opts.version });
+  if (opts.surfaceHints !== false)
+    surfaceToolHints(server);
+  if (opts.banner !== void 0) {
+    console.error(opts.banner);
+  }
+  const deps = opts.deps;
+  for (const register of opts.tools) {
+    await register(server, deps);
+  }
+  return server;
+}
+function withGracefulShutdown(server, opts = {}) {
+  const shouldExit = opts.exit ?? true;
+  let shuttingDown = false;
+  const handler = (signal) => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    void (async () => {
+      try {
+        if (opts.onSignal)
+          await opts.onSignal(signal);
+        await server.close();
+      } catch (err) {
+        console.error(`[mcp-utils] error during graceful shutdown on ${signal}: ${err instanceof Error ? err.message : String(err)}`);
+      } finally {
+        if (shouldExit)
+          process.exit(0);
+      }
+    })();
+  };
+  process.on("SIGINT", () => handler("SIGINT"));
+  process.on("SIGTERM", () => handler("SIGTERM"));
+}
+async function runMcp(opts) {
+  const server = await createMcpServer(opts);
+  const shutdown = opts.shutdown ?? true;
+  if (shutdown !== false) {
+    withGracefulShutdown(server, shutdown === true ? {} : shutdown);
+  }
+  const spec = opts.transport ?? "stdio";
+  const transport = spec === "stdio" ? new StdioServerTransport() : spec;
+  await server.connect(transport);
+  return server;
+}
 
 // node_modules/@chrischall/mcp-utils/dist/config/index.js
 import { homedir } from "node:os";
@@ -34844,6 +34875,34 @@ async function fileBlob(path, opts = {}) {
   return blob;
 }
 
+// node_modules/@chrischall/mcp-utils/dist/http/index.js
+var RateLimitedError = class extends Error {
+  status = 429;
+  constructor(service) {
+    super(`Rate limited (429) by ${service} after retries.`);
+    this.name = "RateLimitedError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var RequestTimeoutError = class extends Error {
+  timeoutMs;
+  constructor(service, timeoutMs) {
+    super(`Request to ${service} timed out after ${timeoutMs}ms.`);
+    this.name = "RequestTimeoutError";
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var ApiError = class extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
 // node_modules/@chrischall/mcp-utils/dist/zod/parse-lenient.js
 function parseLenient(schema, raw, opts) {
   const result = schema.safeParse(raw);
@@ -34878,58 +34937,329 @@ var pageSchema = {
   page_size: external_exports.number().int().min(1).max(200).default(50).describe("Number of items per page (1-200).")
 };
 
+// node_modules/@chrischall/mcp-utils/dist/auth/index.js
+async function resolveAuthPattern(pattern) {
+  const ordered = [
+    pattern.token,
+    pattern.oauth,
+    pattern.sessionScrape,
+    pattern.fetchproxy
+  ];
+  for (const resolver of ordered) {
+    if (resolver)
+      return resolver();
+  }
+  throw createHelpfulError("No auth configured. Provide a token, OAuth credentials, login credentials, or sign in in your browser (fetchproxy fallback).", { hint: "Set one of the supported credential env vars, or sign in in your browser." });
+}
+
 // node_modules/@chrischall/mcp-utils/dist/session/index.js
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync, unlinkSync } from "node:fs";
+import { dirname, join as join2, resolve as resolve2 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+import { randomBytes, createHmac } from "node:crypto";
+function bindingDigest(secret, salt) {
+  return createHmac("sha256", salt).update(secret).digest("hex").slice(0, 32);
+}
+function isEnvelope(raw) {
+  return raw !== null && typeof raw === "object" && raw.v === 1 && "state" in raw;
+}
+var StatePersistenceError = class extends Error {
+  cause;
+  constructor(cause) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.name = "StatePersistenceError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+function createFileStatePersistence(opts) {
+  const { filePath, validate } = opts;
+  const secret = opts.boundTo;
+  return {
+    load() {
+      if (!existsSync(filePath))
+        return null;
+      try {
+        const raw = JSON.parse(readFileSync(filePath, "utf8"));
+        let state;
+        if (isEnvelope(raw)) {
+          const b = raw.boundTo;
+          if (secret === void 0) {
+            if (b !== void 0)
+              return null;
+          } else {
+            if (b === void 0)
+              return null;
+            if (bindingDigest(secret, b.salt) !== b.digest)
+              return null;
+          }
+          state = raw.state;
+        } else {
+          if (secret !== void 0)
+            return null;
+          state = raw;
+        }
+        if (validate !== void 0)
+          return validate(state);
+        return state;
+      } catch {
+        return null;
+      }
+    },
+    save(state) {
+      const dir = dirname(filePath);
+      const tmp = `${filePath}.tmp-${randomBytes(6).toString("hex")}`;
+      const dirExisted = existsSync(dir);
+      try {
+        mkdirSync(dir, { recursive: true, mode: 448 });
+        if (!dirExisted)
+          chmodSync(dir, 448);
+        let boundTo;
+        if (secret !== void 0) {
+          const salt = randomBytes(16).toString("hex");
+          boundTo = { salt, digest: bindingDigest(secret, salt) };
+        }
+        const envelope = { v: 1, ...boundTo !== void 0 ? { boundTo } : {}, state };
+        writeFileSync(tmp, JSON.stringify(envelope, null, 2), { mode: 384 });
+        chmodSync(tmp, 384);
+        renameSync(tmp, filePath);
+        chmodSync(filePath, 384);
+      } catch (err) {
+        try {
+          if (existsSync(tmp))
+            unlinkSync(tmp);
+        } catch {
+        }
+        throw err;
+      }
+    },
+    clear() {
+      try {
+        if (existsSync(filePath))
+          unlinkSync(filePath);
+      } catch {
+      }
+    }
+  };
+}
+function homeOf(env) {
+  return readEnvVar("HOME", { env }) ?? homedir2();
+}
+function resolveStateDir(opts = {}) {
+  const env = opts.env;
+  return join2(readEnvVar("MCP_DATA_DIR", { env }) ?? homeOf(env), opts.subdir ?? "");
+}
+function resolveStateFile(opts) {
+  const override = opts.envVar !== void 0 ? readEnvVar(opts.envVar, { env: opts.env }) : void 0;
+  if (override !== void 0) {
+    if (override === "~")
+      return homeOf(opts.env);
+    if (override.startsWith("~/"))
+      return join2(homeOf(opts.env), override.slice(2));
+    return resolve2(override);
+  }
+  const dirOpts = { env: opts.env };
+  if (opts.subdir !== void 0)
+    dirOpts.subdir = opts.subdir;
+  return join2(resolveStateDir(dirOpts), opts.fileName);
+}
 var TOKEN_REFRESH_SKEW_MS = 5 * 60 * 1e3;
+function defaultIsRefreshRevoked(err) {
+  if (err instanceof RateLimitedError || err instanceof RequestTimeoutError)
+    return false;
+  if (err instanceof ApiError && err.status >= 500)
+    return false;
+  return true;
+}
+function isBearerTokens(raw) {
+  if (raw === null || typeof raw !== "object")
+    return false;
+  const t = raw;
+  if (typeof t.accessToken !== "string" || t.accessToken === "")
+    return false;
+  if (typeof t.expiresAt !== "number" || !Number.isFinite(t.expiresAt))
+    return false;
+  return t.refreshToken === void 0 || typeof t.refreshToken === "string";
+}
 var TokenManager = class {
-  accessToken;
-  refreshToken;
-  expiresAt;
+  tokens;
+  bootstrapFn;
   refreshFn;
   skewMs;
+  persistence;
+  now;
+  isRefreshRevokedFn;
+  onPersistErrorFn;
   inFlight;
+  bootstrapInFlight;
+  /**
+   * Persistence is consulted at most once per process. Without this the
+   * revoked-token recovery below re-reads the SAME rejected record — `clear()`
+   * is optional on {@link StatePersistence} and its failures are swallowed, so
+   * recovery must not depend on it. After the first read the in-memory tokens
+   * (or their deliberate absence) are the truth.
+   */
+  persistenceRead = false;
   constructor(opts) {
-    this.accessToken = opts.initial.accessToken;
-    this.refreshToken = opts.initial.refreshToken;
-    this.expiresAt = opts.initial.expiresAt;
+    if (typeof opts.initial === "function") {
+      this.bootstrapFn = opts.initial;
+    } else {
+      this.tokens = { ...opts.initial };
+    }
     this.refreshFn = opts.refresh;
     this.skewMs = opts.skewMs ?? TOKEN_REFRESH_SKEW_MS;
+    this.persistence = opts.persistence;
+    this.now = opts.now ?? Date.now;
+    this.isRefreshRevokedFn = opts.isRefreshRevoked ?? defaultIsRefreshRevoked;
+    this.onPersistErrorFn = opts.onPersistError;
   }
   /** Whether the token is within the skew window of (or past) expiry. */
   needsRefresh() {
-    return Date.now() >= this.expiresAt - this.skewMs;
+    if (this.tokens === void 0)
+      return false;
+    return this.now() >= this.tokens.expiresAt - this.skewMs;
+  }
+  /**
+   * A stored token is worth using when it is still valid, OR when it carries a
+   * refresh token — an expired-but-refreshable token still saves the login,
+   * which is the expensive half.
+   */
+  isUsable(t) {
+    return this.now() < t.expiresAt - this.skewMs || t.refreshToken !== void 0;
+  }
+  /** Read persisted tokens, guarding shape and usability. Never throws. */
+  async loadPersisted() {
+    if (this.persistence === void 0 || this.persistenceRead)
+      return null;
+    this.persistenceRead = true;
+    try {
+      const raw = await this.persistence.load();
+      if (!isBearerTokens(raw) || !this.isUsable(raw))
+        return null;
+      return raw;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Write tokens. Silent by default (a lost write costs a future login, not this
+   * request); throws a {@link StatePersistenceError} when `onPersistError` does.
+   */
+  async persist(t) {
+    if (this.persistence === void 0)
+      return;
+    try {
+      await this.persistence.save(t);
+    } catch (err) {
+      if (this.onPersistErrorFn === void 0)
+        return;
+      try {
+        this.onPersistErrorFn(err);
+      } catch (hookErr) {
+        throw new StatePersistenceError(hookErr);
+      }
+    }
+  }
+  /** Discard persisted tokens (a refresh they could not satisfy). Never throws. */
+  async clearPersisted() {
+    if (this.persistence?.clear === void 0)
+      return;
+    try {
+      await this.persistence.clear();
+    } catch {
+    }
+  }
+  /** The current tokens, single-flighting the bootstrap if there are none. */
+  ensureTokens() {
+    if (this.tokens !== void 0)
+      return Promise.resolve(this.tokens);
+    if (this.bootstrapInFlight === void 0) {
+      this.bootstrapInFlight = this.runBootstrap().finally(() => {
+        this.bootstrapInFlight = void 0;
+      });
+    }
+    return this.bootstrapInFlight;
+  }
+  /** One bootstrap attempt: persisted tokens if usable, else the login. */
+  async runBootstrap() {
+    const stored = await this.loadPersisted();
+    if (stored !== null) {
+      this.tokens = stored;
+      return stored;
+    }
+    if (this.bootstrapFn === void 0) {
+      throw new Error("TokenManager: no tokens and no bootstrap function to mint them.");
+    }
+    const fresh = await this.bootstrapFn();
+    this.tokens = fresh;
+    try {
+      await this.persist(fresh);
+    } catch (err) {
+      throw err instanceof StatePersistenceError ? err.cause : err;
+    }
+    return fresh;
   }
   /**
    * Single-flight refresh. Concurrent callers share one in-flight promise; it is
    * cleared on settle (success or failure) so a subsequent refresh can proceed.
    */
   refreshNow() {
-    if (!this.inFlight) {
-      const rt = this.refreshToken;
-      if (rt === void 0) {
-        return Promise.reject(new Error("TokenManager: cannot refresh \u2014 no refresh token is available."));
-      }
-      this.inFlight = (async () => {
-        const tok = await this.refreshFn(rt);
-        this.accessToken = tok.accessToken;
-        if (tok.refreshToken !== void 0 && tok.refreshToken !== "") {
-          this.refreshToken = tok.refreshToken;
-        }
-        this.expiresAt = tok.expiresAt;
-      })().finally(() => {
+    if (this.inFlight === void 0) {
+      this.inFlight = this.runRefresh().finally(() => {
         this.inFlight = void 0;
       });
     }
     return this.inFlight;
   }
+  /** One refresh attempt against the current refresh token. */
+  async runRefresh() {
+    const current = this.tokens ?? await this.ensureTokens();
+    const rt = current.refreshToken;
+    if (rt === void 0) {
+      throw new Error("TokenManager: cannot refresh \u2014 no refresh token is available.");
+    }
+    const tok = await this.refreshFn(rt);
+    this.tokens = {
+      accessToken: tok.accessToken,
+      // Rotation is optional: keep the current refresh token when none comes back.
+      refreshToken: tok.refreshToken !== void 0 && tok.refreshToken !== "" ? tok.refreshToken : rt,
+      expiresAt: tok.expiresAt
+    };
+    await this.persist(this.tokens);
+  }
+  /**
+   * Recover from a refresh the current credential could not satisfy — commonly
+   * a refresh token restored from a previous process and revoked since. Without
+   * a bootstrap to fall back on this is terminal; with one, re-minting beats
+   * staying broken forever. Shared so the two entry points cannot diverge.
+   */
+  async reBootstrap(err) {
+    if (err instanceof StatePersistenceError)
+      throw err.cause;
+    if (this.bootstrapFn === void 0)
+      throw err;
+    if (!this.isRefreshRevokedFn(err))
+      throw err;
+    this.tokens = void 0;
+    await this.clearPersisted();
+    return this.ensureTokens();
+  }
   /** Get a valid access token, refreshing proactively inside the skew window. */
   async getAccessToken() {
-    if (this.needsRefresh())
-      await this.refreshNow();
-    return this.accessToken;
+    let tokens = this.tokens ?? await this.ensureTokens();
+    if (this.needsRefresh()) {
+      try {
+        await this.refreshNow();
+      } catch (err) {
+        return (await this.reBootstrap(err)).accessToken;
+      }
+      tokens = this.tokens ?? tokens;
+    }
+    return tokens.accessToken;
   }
-  /** Current absolute expiry (epoch ms). */
+  /** Current absolute expiry (epoch ms), or `0` before the first bootstrap. */
   getExpiresAt() {
-    return this.expiresAt;
+    return this.tokens?.expiresAt ?? 0;
   }
   /**
    * Run an authenticated request with reactive 401-replay. `call` receives a
@@ -34947,16 +35277,21 @@ var TokenManager = class {
     const usedToken = await this.getAccessToken();
     let res = await call(usedToken);
     if (res.status === 401) {
-      if (this.accessToken === usedToken)
-        await this.refreshNow();
-      res = await call(this.accessToken);
+      if (this.tokens?.accessToken === usedToken) {
+        try {
+          await this.refreshNow();
+        } catch (err) {
+          await this.reBootstrap(err);
+        }
+      }
+      res = await call(this.tokens?.accessToken ?? usedToken);
     }
     return res;
   }
 };
 
 // src/client.ts
-import { dirname, join as join4 } from "path";
+import { dirname as dirname2, join as join5 } from "path";
 import { fileURLToPath } from "url";
 
 // node_modules/@fetchproxy/protocol/dist/frames.js
@@ -36133,7 +36468,7 @@ var DEFAULT_BIND_TIMEOUT_MS = 5e3;
 async function electRole(opts) {
   const server = createServer();
   const bindTimeoutMs = opts.bindTimeoutMs ?? DEFAULT_BIND_TIMEOUT_MS;
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     let timer;
     const clearBindTimer = () => {
       if (timer) {
@@ -36149,7 +36484,7 @@ async function electRole(opts) {
           server.close();
         } catch {
         }
-        resolve2({ role: "peer" });
+        resolve3({ role: "peer" });
       } else {
         reject(e);
       }
@@ -36157,7 +36492,7 @@ async function electRole(opts) {
     const onListening = () => {
       clearBindTimer();
       server.removeListener("error", onError);
-      resolve2({ role: "host", server });
+      resolve3({ role: "host", server });
     };
     server.once("error", onError);
     server.once("listening", onListening);
@@ -36319,16 +36654,16 @@ async function awaitSessionReady(ready, opts) {
 
 // node_modules/@fetchproxy/server/dist/extension-trust.js
 import { readFile as readFile2, writeFile as writeFile2, rename, unlink, mkdir as mkdir2, chmod as chmod2 } from "node:fs/promises";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 
 // node_modules/@fetchproxy/server/dist/identity.js
 import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
-import { join as join2 } from "node:path";
-import { homedir as homedir2 } from "node:os";
+import { join as join3 } from "node:path";
+import { homedir as homedir3 } from "node:os";
 var SAFE_PLAIN = /^[A-Za-z0-9._-]+$/;
 var SAFE_SCOPED = /^@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 function defaultIdentityDir() {
-  return join2(homedir2(), ".fetchproxy", "identity");
+  return join3(homedir3(), ".fetchproxy", "identity");
 }
 function safeIdentityFileBase(serverName) {
   if (!serverName || serverName === ".." || serverName.includes("..") || !SAFE_PLAIN.test(serverName) && !SAFE_SCOPED.test(serverName)) {
@@ -36338,7 +36673,7 @@ function safeIdentityFileBase(serverName) {
 }
 async function loadOrCreateIdentity(serverName, dir = defaultIdentityDir()) {
   const safeFile = safeIdentityFileBase(serverName);
-  const path = join2(dir, `${safeFile}.json`);
+  const path = join3(dir, `${safeFile}.json`);
   await mkdir(dir, { recursive: true, mode: 448 });
   try {
     const raw = await readFile(path, "utf8");
@@ -36410,13 +36745,13 @@ function decideExtensionTrust(args) {
   };
 }
 function extensionTrustPath(serverName, dir = defaultIdentityDir()) {
-  return join3(dir, `${safeIdentityFileBase(serverName)}.extension-trust.json`);
+  return join4(dir, `${safeIdentityFileBase(serverName)}.extension-trust.json`);
 }
 function extensionTrustPathHint(serverName) {
   try {
     return extensionTrustPath(serverName);
   } catch {
-    return join3(defaultIdentityDir(), "<server-name>.extension-trust.json");
+    return join4(defaultIdentityDir(), "<server-name>.extension-trust.json");
   }
 }
 function isPin(x) {
@@ -36503,8 +36838,8 @@ async function startHost(opts) {
   let rejectOwnSession;
   let ownSessionReady;
   function resetSessionPromise() {
-    ownSessionReady = new Promise((resolve2, reject) => {
-      resolveOwnSession = resolve2;
+    ownSessionReady = new Promise((resolve3, reject) => {
+      resolveOwnSession = resolve3;
       rejectOwnSession = reject;
     });
     ownSessionReady.catch(() => {
@@ -36725,7 +37060,7 @@ async function startHost(opts) {
     });
   });
   return {
-    close: () => new Promise((resolve2) => {
+    close: () => new Promise((resolve3) => {
       for (const client2 of wss.clients) {
         try {
           client2.terminate();
@@ -36733,7 +37068,7 @@ async function startHost(opts) {
         }
       }
       wss.close(() => {
-        opts.httpServer.close(() => resolve2());
+        opts.httpServer.close(() => resolve3());
       });
     }),
     sendOwnInner: async (inner) => {
@@ -36763,8 +37098,8 @@ async function startHost(opts) {
 var enc3 = new TextEncoder();
 async function startPeer(opts) {
   const ws = new import_websocket.default(`ws://${opts.host}:${opts.port}`);
-  await new Promise((resolve2, reject) => {
-    ws.once("open", () => resolve2());
+  await new Promise((resolve3, reject) => {
+    ws.once("open", () => resolve3());
     ws.once("error", reject);
   });
   const hello = await buildServerHello({
@@ -36794,8 +37129,8 @@ async function startPeer(opts) {
   let pendingPairCode = null;
   let resolveFirstReady;
   let rejectFirstReady;
-  const sessionPromise = new Promise((resolve2, reject) => {
-    resolveFirstReady = resolve2;
+  const sessionPromise = new Promise((resolve3, reject) => {
+    resolveFirstReady = resolve3;
     rejectFirstReady = reject;
   });
   let extensionHello = null;
@@ -36996,6 +37331,17 @@ function classifyBridgeError(err) {
 }
 
 // node_modules/@fetchproxy/server/dist/ws-server.js
+function envWsPort() {
+  const raw = process.env.FETCHPROXY_WS_PORT;
+  if (raw === void 0 || raw.trim() === "")
+    return void 0;
+  if (!/^\d+$/.test(raw.trim()))
+    return void 0;
+  const port = Number(raw.trim());
+  if (!Number.isInteger(port) || port < 1 || port > 65535)
+    return void 0;
+  return port;
+}
 var FetchproxyProtocolError = class extends Error {
   constructor(message) {
     super(message);
@@ -37243,7 +37589,7 @@ var FetchproxyServer = class {
       }
     }
     this.opts = {
-      port: opts.port ?? 37149,
+      port: opts.port ?? envWsPort() ?? 37149,
       host: opts.host ?? "127.0.0.1",
       serverName: opts.serverName,
       version: opts.version,
@@ -37673,8 +38019,8 @@ var FetchproxyServer = class {
   async _fetchOnceWithTimeout(init) {
     const id = this.nextRequestId++;
     const inner = { type: "request", id, op: "fetch", init };
-    const pending = new Promise((resolve2) => {
-      this.pending.set(id, resolve2);
+    const pending = new Promise((resolve3) => {
+      this.pending.set(id, resolve3);
     });
     await this.sendInnerFrame(inner);
     const timeoutMs = this.opts.fetchTimeoutMs;
@@ -37685,12 +38031,12 @@ var FetchproxyServer = class {
     try {
       return await Promise.race([
         pending,
-        new Promise((resolve2) => {
+        new Promise((resolve3) => {
           timer = setTimeout(() => {
             this.pending.delete(id);
             const elapsedMs = Date.now() - start;
             const error51 = `fetchproxy: ${init.url} did not respond within ${timeoutMs}ms`;
-            resolve2({
+            resolve3({
               ok: false,
               error: error51,
               kind: "timeout",
@@ -38052,8 +38398,8 @@ var FetchproxyServer = class {
       const tabUrl = `https://${host}/`;
       inner = { type: "request", id, op: "read_cookies", init: { tabUrl } };
     }
-    const pending = new Promise((resolve2) => {
-      this.pendingReadCookies.set(id, resolve2);
+    const pending = new Promise((resolve3) => {
+      this.pendingReadCookies.set(id, resolve3);
     });
     await this.sendInnerFrame(inner);
     const result = await this._withVerbTimeout(pending, this.pendingReadCookies, id, `https://${host}`);
@@ -38111,8 +38457,8 @@ var FetchproxyServer = class {
         ...cookiePath !== void 0 ? { path: cookiePath } : {}
       }
     };
-    const pending = new Promise((resolve2, reject) => {
-      this.pendingWriteCookies.set(id, { resolve: resolve2, reject });
+    const pending = new Promise((resolve3, reject) => {
+      this.pendingWriteCookies.set(id, { resolve: resolve3, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingWriteCookies, id, `https://${host}`);
@@ -38174,8 +38520,8 @@ var FetchproxyServer = class {
         ...opts.pointers ? { pointers: { ...opts.pointers } } : {}
       }
     };
-    const pending = new Promise((resolve2, reject) => {
-      this.pendingStorage.set(id, { resolve: resolve2, reject });
+    const pending = new Promise((resolve3, reject) => {
+      this.pendingStorage.set(id, { resolve: resolve3, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingStorage, id, `https://${host}`);
@@ -38279,8 +38625,8 @@ var FetchproxyServer = class {
         ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
       }
     };
-    const pending = new Promise((resolve2, reject) => {
-      this.pendingCapture.set(id, { resolve: resolve2, reject });
+    const pending = new Promise((resolve3, reject) => {
+      this.pendingCapture.set(id, { resolve: resolve3, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingCapture, id, `https://${opts.host}${opts.path ?? "/*"}`);
@@ -38364,8 +38710,8 @@ var FetchproxyServer = class {
         ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
       }
     };
-    const pending = new Promise((resolve2, reject) => {
-      this.pendingRedirect.set(id, { resolve: resolve2, reject });
+    const pending = new Promise((resolve3, reject) => {
+      this.pendingRedirect.set(id, { resolve: resolve3, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingRedirect, id, `https://${opts.host}${opts.path ?? "/*"}`);
@@ -38446,8 +38792,8 @@ var FetchproxyServer = class {
         ...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {}
       }
     };
-    const pending = new Promise((resolve2, reject) => {
-      this.pendingDownload.set(id, { resolve: resolve2, reject });
+    const pending = new Promise((resolve3, reject) => {
+      this.pendingDownload.set(id, { resolve: resolve3, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingDownload, id, opts.url);
@@ -38494,8 +38840,8 @@ var FetchproxyServer = class {
         keys: [...opts.keys]
       }
     };
-    const pending = new Promise((resolve2, reject) => {
-      this.pendingIdb.set(id, { resolve: resolve2, reject });
+    const pending = new Promise((resolve3, reject) => {
+      this.pendingIdb.set(id, { resolve: resolve3, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingIdb, id, origin);
@@ -38534,8 +38880,8 @@ var FetchproxyServer = class {
       op: "read_dom",
       init: { origin, names: [...opts.names] }
     };
-    const pending = new Promise((resolve2, reject) => {
-      this.pendingStorage.set(id, { resolve: resolve2, reject });
+    const pending = new Promise((resolve3, reject) => {
+      this.pendingStorage.set(id, { resolve: resolve3, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingStorage, id, origin);
@@ -38580,8 +38926,8 @@ var FetchproxyServer = class {
         ...opts.tabUrl !== void 0 ? { tabUrl: opts.tabUrl } : {}
       }
     };
-    const pending = new Promise((resolve2, reject) => {
-      this.pendingGraphql.set(id, { resolve: resolve2, reject });
+    const pending = new Promise((resolve3, reject) => {
+      this.pendingGraphql.set(id, { resolve: resolve3, reject });
     });
     await this.sendInnerFrame(inner);
     return this._withVerbTimeout(pending, this.pendingGraphql, id, opts.name);
@@ -39074,7 +39420,7 @@ async function loginWithPassword(username, password) {
 // package.json
 var package_default = {
   name: "ofw-mcp",
-  version: "2.10.2",
+  version: "2.12.0",
   license: "MIT",
   mcpName: "io.github.chrischall/ofw-mcp",
   description: "OurFamilyWizard MCP server for Claude \u2014 developed and maintained by AI (Claude Code)",
@@ -39095,18 +39441,20 @@ var package_default = {
     ".claude-plugin",
     "skills",
     ".mcp.json",
-    "server.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: "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "test:watch": "vitest"
+    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": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.18.0",
     "@fetchproxy/bootstrap": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     dotenv: "^17.4.2",
@@ -39126,66 +39474,118 @@ function fetchproxyDisabled() {
   return parseBoolEnv("OFW_DISABLE_FETCHPROXY");
 }
 async function resolveAuth() {
+  const pattern = {};
   const username = readEnvVar("OFW_USERNAME");
   const password = readEnvVar("OFW_PASSWORD");
   if (username && password) {
-    const { token, expiresAt } = await loginWithPassword(username, password);
-    return { token, expiresAt, source: "env" };
+    pattern.sessionScrape = async () => {
+      const { token, expiresAt: expiresAt2 } = await loginWithPassword(username, password);
+      return { credential: token, source: "env", expiresAt: expiresAt2 };
+    };
   }
   if (!fetchproxyDisabled()) {
-    try {
-      const session = await bootstrap({
-        serverName: package_default.name,
-        version: package_default.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.
-        domains: ["ourfamilywizard.com"],
-        declare: {
-          cookies: [],
-          // The web app stores the Bearer token in localStorage["auth"] and
-          // its expiry (ISO string) in localStorage["tokenExpiry"]. Mirroring
-          // both means our 401-replay logic can be slightly smarter, and the
-          // expiry surfaces correctly in diagnostics.
-          localStorage: ["auth", "tokenExpiry"],
-          sessionStorage: [],
-          captureHeaders: []
+    pattern.fetchproxy = async () => {
+      try {
+        const session = await bootstrap({
+          serverName: package_default.name,
+          version: package_default.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.
+          domains: ["ourfamilywizard.com"],
+          declare: {
+            cookies: [],
+            // The web app stores the Bearer token in localStorage["auth"] and
+            // its expiry (ISO string) in localStorage["tokenExpiry"]. Mirroring
+            // both means our 401-replay logic can be slightly smarter, and the
+            // expiry surfaces correctly in diagnostics.
+            localStorage: ["auth", "tokenExpiry"],
+            sessionStorage: [],
+            captureHeaders: []
+          }
+        });
+        const token = session.localStorage["auth"];
+        const expiryRaw = session.localStorage["tokenExpiry"];
+        if (!token) {
+          throw new Error(
+            'localStorage["auth"] missing on ourfamilywizard.com. Sign into OFW in your browser (with the fetchproxy extension installed) and retry.'
+          );
         }
-      });
-      const token = session.localStorage["auth"];
-      const expiryRaw = session.localStorage["tokenExpiry"];
-      if (!token) {
-        throw new Error(
-          'localStorage["auth"] missing on ourfamilywizard.com. Sign into OFW in your browser (with the fetchproxy extension installed) and retry.'
-        );
-      }
-      return {
-        token,
-        expiresAt: expiryRaw ? new Date(expiryRaw) : void 0,
-        source: "fetchproxy"
-      };
-    } catch (e) {
-      if (classifyBridgeError(e) === "bridge_down") {
-        const downErr = e;
+        return {
+          credential: token,
+          source: "fetchproxy",
+          ...expiryRaw ? { expiresAt: new Date(expiryRaw) } : {}
+        };
+      } catch (e) {
+        if (classifyBridgeError(e) === "bridge_down") {
+          const downErr = e;
+          throw new Error(
+            `OFW auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
+          );
+        }
+        const msg = e instanceof Error ? e.message : String(e);
         throw new Error(
-          `OFW auth: fetchproxy bridge is down (extension service worker unreachable after retry). ${downErr.hint}`
+          `OFW auth: no OFW_USERNAME/OFW_PASSWORD set, and fetchproxy fallback failed: ${msg}`
         );
       }
-      const msg = e instanceof Error ? e.message : String(e);
-      throw new Error(
-        `OFW auth: no OFW_USERNAME/OFW_PASSWORD set, and fetchproxy fallback failed: ${msg}`
-      );
-    }
+    };
   }
-  throw new Error(
-    "OFW auth: set OFW_USERNAME + OFW_PASSWORD, or install the fetchproxy extension and sign into ourfamilywizard.com (unset OFW_DISABLE_FETCHPROXY if it is set)."
+  if (!pattern.sessionScrape && !pattern.fetchproxy) {
+    throw new Error(
+      "OFW auth: set OFW_USERNAME + OFW_PASSWORD, or install the fetchproxy extension and sign into ourfamilywizard.com (unset OFW_DISABLE_FETCHPROXY if it is set)."
+    );
+  }
+  const { credential, source, expiresAt } = await resolveAuthPattern(pattern);
+  return {
+    token: credential,
+    // The pattern's `source` is a free-form string; ours is a two-value union,
+    // and both resolvers above set it to a member of that union.
+    source,
+    ...expiresAt ? { expiresAt } : {}
+  };
+}
+
+// src/session-cache.ts
+function sessionCachePath(env = process.env) {
+  return resolveStateFile({
+    env,
+    envVar: "OFW_SESSION_FILE",
+    subdir: ".ofw-mcp",
+    fileName: "session.json"
+  });
+}
+function isTokens(raw) {
+  if (raw === null || typeof raw !== "object") return false;
+  const t = raw;
+  return typeof t.accessToken === "string" && t.accessToken !== "" && typeof t.expiresAt === "number" && (t.refreshToken === void 0 || typeof t.refreshToken === "string");
+}
+function createSessionCache(opts = {}) {
+  const env = opts.env ?? process.env;
+  if (opts.injectedResolver === true) return null;
+  if (!parseBoolEnv("OFW_SESSION_CACHE", { env, default: true })) return null;
+  const username = readEnvVar("OFW_USERNAME", { env });
+  const password = readEnvVar("OFW_PASSWORD", { env });
+  if (username === void 0 || password === void 0) return null;
+  return createFileStatePersistence({
+    filePath: sessionCachePath(env),
+    // Joined on a NUL, written as an escape rather than a literal byte: a
+    // password may contain spaces, so a space-joined pair could collide with
+    // a different pair by shifting the boundary between the two halves.
+    boundTo: [username.trim().toLowerCase(), password].join("\0"),
+    validate: (raw) => isTokens(raw) ? raw : null
+  });
+}
+function reportCacheWriteFailure(err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  console.error(
+    `[ofw-mcp] could not cache the session token (${detail}); continuing without the cache \u2014 every restart will re-authenticate until this is fixed.`
   );
 }
 
 // src/client.ts
 try {
-  const dir = dirname(fileURLToPath(import.meta.url));
-  await loadDotenvSafely({ path: join4(dir, "..", ".env") });
+  const dir = dirname2(fileURLToPath(import.meta.url));
+  await loadDotenvSafely({ path: join5(dir, "..", ".env") });
 } catch {
 }
 function parseContentDispositionFilename(cd) {
@@ -39216,9 +39616,9 @@ var OFWClient = class {
   // Bearer-token lifecycle is delegated to the shared, race-safe TokenManager
   // (proactive refresh inside the skew window, single-flight refresh so a burst
   // of concurrent callers coalesces onto ONE `resolveAuth()`, and a 401-replay
-  // guarded against double-refresh). It is created lazily, seeded with an
-  // already-expired placeholder token so the first request drives the refresh
-  // callback — i.e. the original "log in on first request" behavior.
+  // guarded against double-refresh). It is created lazily, and mints on first
+  // use through the function form of `initial` — see `mint` below for why that
+  // form rather than a seeded placeholder.
   tokenManager;
   // Optional injected auth resolver. When set, the refresh callback uses it
   // instead of the module-level global `resolveAuth` (env-var → fetchproxy
@@ -39232,22 +39632,28 @@ var OFWClient = class {
   }
   getTokenManager() {
     if (!this.tokenManager) {
+      const mint = async () => {
+        const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
+        return {
+          accessToken: token,
+          refreshToken: OFW_REFRESH_SENTINEL,
+          expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime()
+        };
+      };
       this.tokenManager = new TokenManager({
-        initial: { accessToken: "", refreshToken: OFW_REFRESH_SENTINEL, expiresAt: 0 },
+        initial: mint,
+        persistence: createSessionCache({ injectedResolver: this.authResolver !== void 0 }) ?? void 0,
+        onPersistError: reportCacheWriteFailure,
+        // A failed renewal IS a failed login here, so the library's
+        // re-mint-on-revoked recovery would just repeat the call that failed.
+        isRefreshRevoked: () => false,
         skewMs: OFW_TOKEN_EXPIRY_SKEW_MS,
         // Map OFW's mint/refresh onto the refresh callback. `resolveAuth()`
         // returns a token and a best-effort expiry; when the fetchproxy path
         // can't supply one we fall back to the same 6h estimate the password
         // path uses (the 401-replay covers a wrong guess). We re-arm the
         // sentinel so the manager can refresh again later.
-        refresh: async () => {
-          const { token, expiresAt } = await (this.authResolver ?? resolveAuth)();
-          return {
-            accessToken: token,
-            refreshToken: OFW_REFRESH_SENTINEL,
-            expiresAt: (expiresAt ?? new Date(Date.now() + OFW_TOKEN_TTL_MS)).getTime()
-          };
-        }
+        refresh: mint
       });
     }
     return this.tokenManager;
@@ -40071,25 +40477,25 @@ async function syncAll(client2, opts, store) {
 
 // src/config.ts
 import { createHash } from "node:crypto";
-import { homedir as homedir3 } from "node:os";
-import { join as join5 } from "node:path";
+import { homedir as homedir4 } from "node:os";
+import { join as join6 } from "node:path";
 function readCacheIdentity() {
   return readEnvVar("OFW_CACHE_IDENTITY") ?? readEnvVar("OFW_USERNAME") ?? "_default";
 }
 function getCacheDir() {
   const override = process.env.OFW_CACHE_DIR;
   if (override && override.trim().length > 0) return override.trim();
-  return join5(homedir3(), ".cache", "ofw-mcp");
+  return join6(homedir4(), ".cache", "ofw-mcp");
 }
 function getCacheDbPath() {
   const identity = readCacheIdentity();
   const hash2 = createHash("sha256").update(identity).digest("hex").slice(0, 16);
-  return join5(getCacheDir(), `${hash2}.db`);
+  return join6(getCacheDir(), `${hash2}.db`);
 }
 function getAttachmentsDir() {
   const override = process.env.OFW_ATTACHMENTS_DIR;
   if (override && override.trim().length > 0) return override.trim();
-  return join5(homedir3(), "Downloads", "ofw-mcp");
+  return join6(homedir4(), "Downloads", "ofw-mcp");
 }
 function getWriteMode() {
   const raw = process.env.OFW_WRITE_MODE;
@@ -41459,8 +41865,8 @@ async function extractAttachment(bytes, mimeType, fileName, opts = {}) {
 }
 
 // src/tools/attachments.ts
-import { readFileSync, statSync, mkdirSync, writeFileSync } from "node:fs";
-import { basename, dirname as dirname2, extname } from "node:path";
+import { readFileSync as readFileSync2, statSync, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { basename, dirname as dirname3, extname } from "node:path";
 var MIME_BY_EXT = {
   ".pdf": "application/pdf",
   ".png": "image/png",
@@ -41534,14 +41940,14 @@ var NodeAttachmentIO = class {
   }
   readDownloaded(path) {
     try {
-      return readFileSync(path);
+      return readFileSync2(path);
     } catch {
       return null;
     }
   }
   writeDownload(dest, bytes) {
-    mkdirSync(dirname2(dest), { recursive: true });
-    writeFileSync(dest, bytes);
+    mkdirSync2(dirname3(dest), { recursive: true });
+    writeFileSync2(dest, bytes);
   }
 };
 
@@ -41605,7 +42011,54 @@ async function buildInlineDelivery(input) {
 }
 
 // src/tools/messages.ts
-import { basename as basename2, join as join6 } from "node:path";
+import { basename as basename2, join as join7 } from "node:path";
+
+// src/tools/pagination.ts
+function pageState(input) {
+  const hasMore = input.page * input.size < input.total;
+  return { hasMore, nextPage: hasMore ? input.page + 1 : null };
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function recordArray(root) {
+  if (Array.isArray(root.data)) return root.data;
+  for (const value of Object.values(root)) {
+    if (Array.isArray(value)) return value;
+  }
+  return null;
+}
+function readUpstreamPaging(payload) {
+  const root = asRecord(payload);
+  const rows = root === null ? null : recordArray(root);
+  const meta3 = root === null ? null : asRecord(root.metadata);
+  const total = meta3 !== null && typeof meta3.totalElements === "number" && Number.isFinite(meta3.totalElements) ? meta3.totalElements : null;
+  const last = meta3 !== null && typeof meta3.last === "boolean" ? meta3.last : null;
+  return { returned: rows?.length ?? 0, total, last };
+}
+function offsetState(input) {
+  const last = input.last ?? null;
+  const consumed = input.start - input.base + input.returned;
+  const hasMore = last !== null ? !last : input.total !== null ? consumed < input.total : input.returned >= input.max;
+  return { hasMore, nextStart: hasMore ? input.start + input.max : null };
+}
+function withPaginationFirst(input) {
+  const body = asRecord(input.payload);
+  if (body === null) return null;
+  const scope = input.total !== null ? ` of ${input.total}` : "";
+  const head = {
+    hasMore: input.state.hasMore,
+    nextStart: input.state.nextStart,
+    start: input.start,
+    max: input.max,
+    returned: input.returned,
+    ...input.total !== null ? { total: input.total } : {},
+    paginationNote: input.state.hasMore ? `PARTIAL: this response holds ${input.returned} record(s) starting at ${input.start}${scope}. ${input.hint} Do not state a total or an absence from this response alone.` : `This response reaches the end of the list${scope === "" ? "" : ` (${input.total} record(s) in total)`}.`
+  };
+  return { ...head, ...body, ...head };
+}
+
+// src/tools/messages.ts
 var DateSchema = external_exports.looseObject({ dateTime: external_exports.string() });
 var SentDetailSchema = external_exports.looseObject({
   subject: external_exports.string().optional(),
@@ -41741,7 +42194,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     return jsonResponse({ folders: data, freshness });
   });
   server.registerTool("ofw_list_messages", {
-    description: 'List messages from the local OurFamilyWizard cache. Supports filtering by folder, date range, and a substring query on subject+body. Pagination is offset-based but if you know what you want (a date range, a topic), prefer the filters over walking pages \u2014 the cache may have 1000+ messages. 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.',
+    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: false },
     inputSchema: {
       folderId: external_exports.string().describe('Folder name: "inbox", "sent", or "both" (default "both")').optional(),
@@ -41750,11 +42203,13 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       since: external_exports.string().describe("ISO date or datetime \u2014 only messages with sent_at >= since (inclusive)").optional(),
       until: external_exports.string().describe("ISO date or datetime \u2014 only messages with sent_at < until (exclusive)").optional(),
       q: external_exports.string().describe("Substring match on subject AND body (case-insensitive). Use to find messages on a specific topic.").optional(),
+      sort: external_exports.enum(["newest", "oldest"]).describe('Result order: "newest" (default, newest first) or "oldest" (oldest first). This decides which end a truncated page keeps \u2014 with "newest" page 1 of a wide date range holds its most RECENT slice, with "oldest" its earliest. Use "oldest" to start at the old end of a range instead of paging to it.').optional(),
       autoRefresh: external_exports.boolean().describe(AUTO_REFRESH_DESC).optional()
     }
   }, async (args) => {
     const page = args.page ?? 1;
     const size = args.size ?? 50;
+    const sort = args.sort ?? "newest";
     const folderArg = args.folderId ?? "both";
     let folder;
     if (folderArg === "inbox") folder = "inbox";
@@ -41780,7 +42235,7 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
       isEmpty: (v) => v.total === 0,
       read: async () => {
         const total2 = await cache.countMessages(filter);
-        const messages2 = (await cache.listMessages({ ...filter, page, size })).map((m) => withReadState(m));
+        const messages2 = (await cache.listMessages({ ...filter, page, size, sort })).map((m) => withReadState(m));
         const freshness2 = await buildFreshness(cache, { source: "cache", folders });
         return { messages: messages2, total: total2, freshness: freshness2 };
       }
@@ -41797,7 +42252,19 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     const { messages, total, freshness } = value;
     const fullSlice = page === 1 && messages.length === total;
     const complete = fullSlice && freshness.staleness === "fresh" && freshness.historyComplete;
-    const payload = { messages, total, page, size, complete, freshness };
+    const { hasMore, nextPage } = pageState({ page, size, total });
+    const payload = {
+      complete,
+      hasMore,
+      nextPage,
+      // The honest record count, as a scalar and ahead of the array — a
+      // consumer never has to reach `messages` to learn how many came back.
+      returned: messages.length,
+      total,
+      page,
+      size,
+      sort
+    };
     if (!complete) {
       payload.completeNote = [
         !fullSlice ? `this page holds ${messages.length} of ${total} matching cached messages` : null,
@@ -41808,11 +42275,13 @@ function registerMessageTools(server, client2, cacheProvider, attachmentIO) {
     if (total === 0) {
       payload.note = 'No messages match these filters, and the cache IS verified-fresh for these folders \u2014 so this is a real "nothing matched", not a stale-cache artefact. If you expected results, relax the filters.';
     } else if (page * size < total) {
-      payload.note = `Showing ${(page - 1) * size + 1}\u2013${(page - 1) * size + messages.length} of ${total}. Increase 'page' to see more, or narrow with since/until/q.`;
+      payload.note = `Showing ${(page - 1) * size + 1}\u2013${(page - 1) * size + messages.length} of ${total}, ${sort} first. Increase 'page' to see more, narrow with since/until/q, or set sort:"${sort === "newest" ? "oldest" : "newest"}" to start from the other end.`;
     }
     if (refreshed) {
       payload.autoRefreshed = true;
     }
+    payload.freshness = freshness;
+    payload.messages = messages;
     return jsonResponse(payload);
   });
   server.registerTool("ofw_get_message", {
@@ -42259,7 +42728,16 @@ ${JSON.stringify(
     const { drafts, total, freshness, serverConfirmed } = value;
     const fullSlice = page === 1 && drafts.length === total;
     const complete = serverConfirmed && fullSlice;
-    const payload = { drafts, total, page, size, complete, freshness };
+    const { hasMore, nextPage } = pageState({ page, size, total });
+    const payload = {
+      complete,
+      hasMore,
+      nextPage,
+      returned: drafts.length,
+      total,
+      page,
+      size
+    };
     if (!complete) {
       payload.completeNote = [
         !fullSlice ? `this page holds ${drafts.length} of ${total} cached drafts` : null,
@@ -42278,6 +42756,8 @@ ${JSON.stringify(
     if (verifyNote !== null) {
       payload.verifyNote = verifyNote;
     }
+    payload.freshness = freshness;
+    payload.drafts = drafts;
     return jsonResponse(payload);
   });
   if (allowDrafts) server.registerTool("ofw_save_draft", {
@@ -42509,7 +42989,16 @@ ${text}` : text);
         unread.push({ id: msg.id, subject: msg.subject, sentAt: msg.sentAt, unreadBy });
       }
     }
-    const payload = { unread, scanned: sent.length, total, complete, freshness };
+    const { hasMore, nextPage } = pageState({ page, size, total });
+    const payload = {
+      complete,
+      hasMore,
+      nextPage,
+      total,
+      scanned: sent.length,
+      page,
+      size
+    };
     if (!complete) {
       payload.completeNote = `This verdict covers the ${sent.length} of ${total} cached sent messages on this page${freshness.staleness === "fresh" ? "" : `, from a cache that is "${freshness.staleness}"`}. It is not a statement about every message you have sent.`;
     }
@@ -42519,6 +43008,8 @@ ${text}` : text);
     if (refreshed) {
       payload.autoRefreshed = true;
     }
+    payload.freshness = freshness;
+    payload.unread = unread;
     return jsonResponse(payload);
   });
   if (allowDrafts) server.registerTool("ofw_upload_attachment", {
@@ -42615,9 +43106,9 @@ ${text}` : text);
     if (args.saveTo) {
       const isDirArg = args.saveTo.endsWith("/") || args.saveTo.endsWith("\\");
       const abs = expandPath2(args.saveTo);
-      dest = isDirArg ? join6(abs, `${fileId}-${safeName}`) : abs;
+      dest = isDirArg ? join7(abs, `${fileId}-${safeName}`) : abs;
     } else {
-      dest = join6(getAttachmentsDir(), `${fileId}-${safeName}`);
+      dest = join7(getAttachmentsDir(), `${fileId}-${safeName}`);
     }
     const extractOnDisk = args.extract === true;
     if (!args.force && cached2.downloadedPath === dest) {
@@ -43037,17 +43528,27 @@ function registerExpenseTools(server, client2) {
     return jsonResponse(data);
   });
   server.registerTool("ofw_list_expenses", {
-    description: "List OurFamilyWizard expenses with pagination",
+    description: "List OurFamilyWizard expenses. Offset-paged via start/max. 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 expense total or an absence from one page.",
     annotations: { readOnlyHint: true },
     inputSchema: {
-      start: external_exports.number().int().min(0).describe("Start offset (default 0)").optional(),
+      start: external_exports.number().int().min(0).describe("Start offset, 0-based (default 0). To continue a listing, pass the `nextStart` from the previous response.").optional(),
       max: external_exports.number().int().min(1).describe("Max results (default 20)").optional()
     }
   }, async (args) => {
     const start = args.start ?? 0;
     const max = args.max ?? 20;
     const data = await client2.request("GET", `/pub/v2/expense/expenses?start=${start}&max=${max}`);
-    return jsonResponse(data);
+    const { returned, total, last } = readUpstreamPaging(data);
+    const wrapped = withPaginationFirst({
+      state: offsetState({ start, max, returned, total, last, base: 0 }),
+      start,
+      max,
+      returned,
+      total,
+      hint: `Re-call ofw_list_expenses with start:${start + max}.`,
+      payload: data
+    });
+    return jsonResponse(wrapped ?? data);
   });
   if (allowWrites) server.registerTool("ofw_create_expense", {
     description: "Log a new expense in OurFamilyWizard",
@@ -43066,17 +43567,27 @@ function registerExpenseTools(server, client2) {
 function registerJournalTools(server, client2) {
   const allowWrites = getWriteMode() === "all";
   server.registerTool("ofw_list_journal_entries", {
-    description: "List OurFamilyWizard 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 },
     inputSchema: {
-      start: external_exports.number().int().min(1).describe("Start offset (default 1)").optional(),
+      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()
     }
   }, async (args) => {
     const start = args.start ?? 1;
     const max = args.max ?? 10;
     const data = await client2.request("GET", `/pub/v1/journals?start=${start}&max=${max}`);
-    return jsonResponse(data);
+    const { returned, total, last } = readUpstreamPaging(data);
+    const wrapped = withPaginationFirst({
+      state: offsetState({ start, max, returned, total, last, base: 1 }),
+      start,
+      max,
+      returned,
+      total,
+      hint: `Re-call ofw_list_journal_entries with start:${start + max}.`,
+      payload: data
+    });
+    return jsonResponse(wrapped ?? data);
   });
   if (allowWrites) server.registerTool("ofw_create_journal_entry", {
     description: "Create a new journal entry in OurFamilyWizard",
@@ -43093,8 +43604,8 @@ function registerJournalTools(server, client2) {
 
 // src/cache/node.ts
 import { DatabaseSync } from "node:sqlite";
-import { mkdirSync as mkdirSync2, chmodSync, existsSync } from "node:fs";
-import { dirname as dirname3 } from "node:path";
+import { mkdirSync as mkdirSync3, chmodSync as chmodSync2, existsSync as existsSync2 } from "node:fs";
+import { dirname as dirname4 } from "node:path";
 
 // src/cache/store.ts
 function rowFromDb(r) {
@@ -43332,9 +43843,10 @@ var OFWCacheCore = class {
   listMessages(opts) {
     const { where, params } = buildMessageFilter(opts);
     const offset = (opts.page - 1) * opts.size;
+    const dir = opts.sort === "oldest" ? "ASC" : "DESC";
     const rows = this.db.all(
       `SELECT * FROM messages ${where}
-       ORDER BY sent_at DESC, id DESC
+       ORDER BY sent_at ${dir}, id ${dir}
        LIMIT ? OFFSET ?`,
       [...params, opts.size, offset]
     );
@@ -43677,10 +44189,10 @@ var NodeSqlDriver = class {
   }
 };
 function enforceCachePermissions(dbPath) {
-  chmodSync(dirname3(dbPath), 448);
-  chmodSync(dbPath, 384);
+  chmodSync2(dirname4(dbPath), 448);
+  chmodSync2(dbPath, 384);
   for (const sibling of [`${dbPath}-wal`, `${dbPath}-shm`]) {
-    if (existsSync(sibling)) chmodSync(sibling, 384);
+    if (existsSync2(sibling)) chmodSync2(sibling, 384);
   }
 }
 var OFWCache = class _OFWCache extends LocalCacheStore {
@@ -43691,7 +44203,7 @@ var OFWCache = class _OFWCache extends LocalCacheStore {
   db;
   static open(path) {
     const memory = path === ":memory:";
-    if (!memory) mkdirSync2(dirname3(path), { recursive: true });
+    if (!memory) mkdirSync3(dirname4(path), { recursive: true });
     const db = new DatabaseSync(path);
     if (!memory) enforceCachePermissions(path);
     db.exec("PRAGMA journal_mode = WAL");
@@ -43721,7 +44233,7 @@ var nodeCacheProvider = () => nodeCache ??= OFWCache.open(getCacheDbPath());
 var nodeAttachmentIO = new NodeAttachmentIO();
 await runMcp({
   name: "ofw",
-  version: "2.10.2",
+  version: "2.12.0",
   // x-release-please-version
   deps: client,
   tools: [