@json-to-office/mcp-server 1.5.0 → 1.8.0

package/dist/cli.js

@@ -7,7 +7,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { McpServer } from "@modelcontextprotocol/server";
 
 // src/lib/version.ts
-var SERVER_VERSION = true ? "1.5.0" : "dev-mode";
+var SERVER_VERSION = true ? "1.8.0" : "dev-mode";
 var SERVER_NAME = "json-to-office";
 var PACKAGE_NAME = "@json-to-office/mcp-server";
 
@@ -420,9 +420,9 @@ var ROOT_SENTINELS = /* @__PURE__ */ new Set(["", "/", "#", "root"]);
 function escapePointerSegment(segment) {
   return segment.replace(/~/g, "~0").replace(/\//g, "~1");
 }
-function toJsonPointer(path6) {
-  if (path6 === void 0) return void 0;
-  const trimmed = path6.trim();
+function toJsonPointer(path7) {
+  if (path7 === void 0) return void 0;
+  const trimmed = path7.trim();
   if (ROOT_SENTINELS.has(trimmed)) return "";
   const segments = trimmed.startsWith("/") ? trimmed.slice(1).split("/") : trimmed.replace(/\[(\d+)\]/g, ".$1").split(".").filter((segment) => segment !== "");
   if (segments.length === 0) return "";
@@ -623,11 +623,11 @@ async function probeService(rawUrl, envVar) {
   }
   const port = Number(target.port || (target.protocol === "https:" ? 443 : 80));
   const net = await import("net");
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     const socket = net.connect({ host: target.hostname, port });
     const settle = (detail) => {
       socket.destroy();
-      resolve2({
+      resolve3({
         available: detail === void 0,
         url: target.origin,
         envVar,
@@ -667,7 +667,7 @@ function register(server, deps) {
     "jto_info",
     {
       title: "Server info",
-      description: "Versions, supported formats with each renderer and whether its backend loads here, workspace availability, output-root and size limits, and whether the optional host dependencies (LibreOffice and poppler for jto_preview, a Highcharts export server for the DOCX `highcharts` component) are present on this host. Call this first.",
+      description: "Versions, supported formats with each renderer and whether its backend loads here, workspace availability and whether workspaces survive a lost connection, output-root and size limits, and whether the optional host dependencies (LibreOffice and poppler for jto_preview, a Highcharts export server for the DOCX `highcharts` component) are present on this host. Call this first.",
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: S({
         type: "object",
@@ -752,9 +752,17 @@ function register(server, deps) {
               type: "object",
               properties: {
                 available: { type: "boolean" },
-                open: { type: "integer" }
+                open: { type: "integer" },
+                persistent: {
+                  type: "boolean",
+                  description: "True when revisions are mirrored to disk and survive a lost connection; false when handles are memory-only, which is the default."
+                },
+                root: {
+                  type: "string",
+                  description: "Directory the revisions are mirrored to, when persistent."
+                }
               },
-              required: ["available", "open"],
+              required: ["available", "open", "persistent"],
               additionalProperties: false
             },
             output: {
@@ -915,7 +923,11 @@ function register(server, deps) {
             formats,
             workspaces: {
               available: store.available,
-              open: listed.ok ? listed.records.length : 0
+              open: listed.ok ? listed.records.length : 0,
+              persistent: deps.workspacePersistence !== void 0,
+              ...deps.workspacePersistence && {
+                root: deps.workspacePersistence.root
+              }
             },
             output: {
               root: deps.outputRoot.path,
@@ -3136,9 +3148,9 @@ async function digestAssets(document, baseDir) {
     [...references].map(async (reference) => {
       const resolved = path4.resolve(root, reference);
       try {
-        const stat = await fs4.stat(resolved);
-        if (!stat.isFile()) return;
-        entries.push(`${resolved}|${stat.size}|${stat.mtimeMs}`);
+        const stat2 = await fs4.stat(resolved);
+        if (!stat2.isFile()) return;
+        entries.push(`${resolved}|${stat2.size}|${stat2.mtimeMs}`);
       } catch {
       }
     })
@@ -3168,8 +3180,8 @@ function collectAssetReferences(value, into) {
 async function digestThemeFile(themePath) {
   if (!themePath) return "none";
   try {
-    const stat = await fs4.stat(themePath);
-    return `${path4.resolve(themePath)}|${stat.size}|${stat.mtimeMs}`;
+    const stat2 = await fs4.stat(themePath);
+    return `${path4.resolve(themePath)}|${stat2.size}|${stat2.mtimeMs}`;
   } catch {
     return `${path4.resolve(themePath)}|missing`;
   }
@@ -3241,18 +3253,18 @@ function missingDependencyFailure(dependencies) {
   );
 }
 async function binaryIdentity(binary, args, signal) {
-  const [version, stat] = await Promise.all([
+  const [version, stat2] = await Promise.all([
     readVersion(binary, args, signal),
     fs5.stat(binary).catch(() => void 0)
   ]);
   const identity = [
     version ?? "unknown",
-    stat ? `${stat.size}:${stat.mtimeMs}` : "nostat"
+    stat2 ? `${stat2.size}:${stat2.mtimeMs}` : "nostat"
   ].join("|");
   return { identity, ...version !== void 0 && { version } };
 }
 function readVersion(binary, args, signal) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     execFile(
       binary,
       args,
@@ -3266,8 +3278,8 @@ function readVersion(binary, args, signal) {
         const text = `${stdout ?? ""}
 ${stderr ?? ""}`.trim();
         const line = text.split("\n")[0]?.trim();
-        if (!line && error) return resolve2(void 0);
-        resolve2(line || void 0);
+        if (!line && error) return resolve3(void 0);
+        resolve3(line || void 0);
       }
     );
   });
@@ -3312,12 +3324,12 @@ function defaultPreviewCacheDir() {
 }
 var CACHE_ENTRY_NAME = /^[a-f0-9]{64}\.(?:png|meta\.json)(?:\.tmp-\d+-\d+)?$/;
 async function inspectPrivateCacheDir(cacheDir) {
-  const stat = await fs6.lstat(cacheDir).catch(() => void 0);
-  if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) return false;
-  if (typeof process.getuid === "function" && stat.uid !== process.getuid()) {
+  const stat2 = await fs6.lstat(cacheDir).catch(() => void 0);
+  if (!stat2 || stat2.isSymbolicLink() || !stat2.isDirectory()) return false;
+  if (typeof process.getuid === "function" && stat2.uid !== process.getuid()) {
     return false;
   }
-  if (process.platform !== "win32" && (stat.mode & 63) !== 0) {
+  if (process.platform !== "win32" && (stat2.mode & 63) !== 0) {
     try {
       await fs6.chmod(cacheDir, 448);
     } catch {
@@ -3347,9 +3359,9 @@ async function sweepPreviewCache(cacheDir, options = {}) {
   for (const name of names) {
     if (!CACHE_ENTRY_NAME.test(name)) continue;
     const file = path5.join(cacheDir, name);
-    const stat = await fs6.lstat(file).catch(() => void 0);
-    if (!stat?.isFile()) continue;
-    entries.push({ file, mtimeMs: stat.mtimeMs, size: stat.size });
+    const stat2 = await fs6.lstat(file).catch(() => void 0);
+    if (!stat2?.isFile()) continue;
+    entries.push({ file, mtimeMs: stat2.mtimeMs, size: stat2.size });
   }
   const doomed = entries.filter((entry) => now - entry.mtimeMs > maxAgeMs);
   const kept = entries.filter((entry) => now - entry.mtimeMs <= maxAgeMs).sort((a, b) => a.mtimeMs - b.mtimeMs);
@@ -3436,7 +3448,7 @@ function countPdfPages(pdf) {
   return matches ? matches.length : 0;
 }
 function exec(binary, args, timeoutMs, options = {}) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     execFile2(
       binary,
       args,
@@ -3447,7 +3459,7 @@ function exec(binary, args, timeoutMs, options = {}) {
         env: options.env ? { ...process.env, ...options.env } : process.env,
         ...options.signal && { signal: options.signal }
       },
-      (error) => error ? reject(error) : resolve2()
+      (error) => error ? reject(error) : resolve3()
     );
   });
 }
@@ -3541,7 +3553,7 @@ async function resolvePdfinfo(pdftoppmPath) {
   return status.available ? status.path : void 0;
 }
 async function pdfinfoPageCount(pdfinfo, pdfPath, signal) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     execFile2(
       pdfinfo,
       [pdfPath],
@@ -3552,9 +3564,9 @@ async function pdfinfoPageCount(pdfinfo, pdfPath, signal) {
         ...signal && { signal }
       },
       (error, stdout) => {
-        if (error && !stdout) return resolve2(void 0);
+        if (error && !stdout) return resolve3(void 0);
         const match = /^Pages:\s+(\d+)/m.exec(stdout ?? "");
-        resolve2(match ? Number(match[1]) : void 0);
+        resolve3(match ? Number(match[1]) : void 0);
       }
     );
   });
@@ -4667,9 +4679,9 @@ function compilePatch(operations) {
         }
       );
     }
-    const path6 = parsePointer(raw.path);
-    if (!path6.ok) {
-      return problem(PATCH_ERROR_CODES.INVALID_POINTER, path6.message, index, {
+    const path7 = parsePointer(raw.path);
+    if (!path7.ok) {
+      return problem(PATCH_ERROR_CODES.INVALID_POINTER, path7.message, index, {
         context: { op, pointer: raw.path },
         suggestion: 'Pointers are RFC 6901: "/children/0/props/text", with "~0" for "~" and "~1" for "/".'
       });
@@ -4677,7 +4689,7 @@ function compilePatch(operations) {
     const entry = {
       op,
       path: raw.path,
-      tokens: path6.tokens
+      tokens: path7.tokens
     };
     if (VALUE_OPS.has(op)) {
       if (raw.value === void 0) {
@@ -5027,12 +5039,338 @@ function jsonEqualTokens(left, right) {
 }
 
 // src/workspace/store.ts
+import { randomBytes as randomBytes3 } from "crypto";
+
+// src/workspace/persistence.ts
+import * as fs7 from "fs/promises";
+import * as path6 from "path";
 import { randomBytes as randomBytes2 } from "crypto";
+var WORKSPACE_DIR_ENV = "JTO_MCP_WORKSPACE_DIR";
+var SCHEMA_VERSION = 1;
+var META_FILE = "meta.json";
+var REVISION_PREFIX = "rev-";
+var REVISION_SUFFIX = ".json";
+var TEMP_SUFFIX = ".tmp";
+var STALE_TEMP_MS = 60 * 60 * 1e3;
+var SAFE_HANDLE = /^[A-Za-z0-9_-]{1,128}$/;
+function isPersistableHandle(handle) {
+  return SAFE_HANDLE.test(handle);
+}
+var DEFAULT_PERSISTENCE_LIMITS = {
+  maxWorkspaces: 32,
+  maxRevisionsPerWorkspace: 9,
+  maxEntryBytes: 16 * 1024 * 1024
+};
+function createWorkspacePersistence(options = {}) {
+  const env = options.env ?? process.env;
+  const configured = options.flagDir?.trim() || env[WORKSPACE_DIR_ENV]?.trim();
+  if (!configured) return void 0;
+  return createWorkspacePersistenceAt(path6.resolve(configured), options);
+}
+function createWorkspacePersistenceAt(root, limits = {}) {
+  const bounds = {
+    maxWorkspaces: limits.maxWorkspaces ?? DEFAULT_PERSISTENCE_LIMITS.maxWorkspaces,
+    maxRevisionsPerWorkspace: limits.maxRevisionsPerWorkspace ?? DEFAULT_PERSISTENCE_LIMITS.maxRevisionsPerWorkspace,
+    maxEntryBytes: limits.maxEntryBytes ?? DEFAULT_PERSISTENCE_LIMITS.maxEntryBytes
+  };
+  let ensured;
+  const authored = /* @__PURE__ */ new Map();
+  function claim(handle, revision) {
+    const owned = authored.get(handle) ?? /* @__PURE__ */ new Set();
+    owned.add(revision);
+    authored.set(handle, owned);
+  }
+  async function ensureRoot() {
+    if (ensured === void 0) {
+      ensured = fs7.mkdir(root, { recursive: true, mode: 448 }).then(
+        () => void 0,
+        (error) => {
+          ensured = void 0;
+          throw error;
+        }
+      );
+    }
+    return ensured;
+  }
+  function dirFor(handle) {
+    return path6.join(root, handle);
+  }
+  async function writeAtomic2(target, contents) {
+    const temp = `${target}.${randomBytes2(6).toString("hex")}${TEMP_SUFFIX}`;
+    try {
+      await fs7.writeFile(temp, contents, { encoding: "utf8", mode: 384 });
+      await fs7.rename(temp, target);
+    } catch (error) {
+      await fs7.rm(temp, { force: true }).catch(() => void 0);
+      throw error;
+    }
+  }
+  function revisionFile(handle, revision) {
+    return path6.join(
+      dirFor(handle),
+      `${REVISION_PREFIX}${revision}${REVISION_SUFFIX}`
+    );
+  }
+  async function readMeta(handle) {
+    let raw;
+    try {
+      raw = await fs7.readFile(path6.join(dirFor(handle), META_FILE), "utf8");
+    } catch {
+      return void 0;
+    }
+    return parseMeta(raw, handle);
+  }
+  async function readRevision(handle, revision) {
+    let text;
+    try {
+      text = await fs7.readFile(revisionFile(handle, revision), "utf8");
+    } catch {
+      return void 0;
+    }
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        return void 0;
+    } catch {
+      return void 0;
+    }
+    return { revision, text, bytes: Buffer.byteLength(text, "utf8") };
+  }
+  async function handleDirs() {
+    try {
+      const entries = await fs7.readdir(root, { withFileTypes: true });
+      return entries.filter(
+        (entry) => entry.isDirectory() && isPersistableHandle(entry.name)
+      ).map((entry) => entry.name);
+    } catch {
+      return [];
+    }
+  }
+  async function pruneWorkspaces(incoming) {
+    const handles = (await handleDirs()).filter(
+      (handle) => handle !== incoming
+    );
+    const excess = handles.length + 1 - bounds.maxWorkspaces;
+    if (excess <= 0) return;
+    const metas = await Promise.all(
+      handles.map(async (handle) => ({
+        handle,
+        // An unreadable entry sorts first: it is the one worth losing.
+        updatedAt: (await readMeta(handle))?.updatedAt ?? 0
+      }))
+    );
+    metas.sort((a, b) => a.updatedAt - b.updatedAt);
+    for (const victim of metas.slice(0, excess)) {
+      await fs7.rm(dirFor(victim.handle), { recursive: true, force: true }).catch(() => void 0);
+      authored.delete(victim.handle);
+    }
+  }
+  async function pruneRevisions(handle, retained) {
+    let names;
+    try {
+      names = await fs7.readdir(dirFor(handle));
+    } catch {
+      return;
+    }
+    const owned = authored.get(handle);
+    for (const name of names) {
+      const target = path6.join(dirFor(handle), name);
+      if (name.endsWith(TEMP_SUFFIX)) {
+        if (await isStale(target)) {
+          await fs7.rm(target, { force: true }).catch(() => void 0);
+        }
+        continue;
+      }
+      const revision = revisionOf(name);
+      if (revision === void 0 || retained.has(revision)) continue;
+      await fs7.rm(target, { force: true }).catch(() => void 0);
+      owned?.delete(revision);
+    }
+  }
+  return {
+    root,
+    limits: bounds,
+    async save(snapshot) {
+      if (!isPersistableHandle(snapshot.handle)) {
+        throw new Error(
+          `Workspace handle ${JSON.stringify(
+            snapshot.handle
+          )} cannot be used as a directory name.`
+        );
+      }
+      if (snapshot.head.bytes > bounds.maxEntryBytes) {
+        throw new Error(
+          `Revision ${snapshot.head.revision} is ${snapshot.head.bytes} bytes, over the ${bounds.maxEntryBytes}-byte persistence limit.`
+        );
+      }
+      await ensureRoot();
+      const dir = dirFor(snapshot.handle);
+      const fresh = !await exists(dir);
+      if (fresh) await pruneWorkspaces(snapshot.handle);
+      await fs7.mkdir(dir, { recursive: true, mode: 448 });
+      const files = [snapshot.head];
+      const retained = /* @__PURE__ */ new Set([snapshot.head.revision]);
+      const pinned = [];
+      for (const pin of [...snapshot.pins].sort(
+        (a, b) => b.revision - a.revision
+      )) {
+        if (!retained.has(pin.revision)) {
+          if (files.length >= bounds.maxRevisionsPerWorkspace) continue;
+          files.push(pin);
+          retained.add(pin.revision);
+        }
+        pinned.push(pin.revision);
+      }
+      const owned = authored.get(snapshot.handle);
+      for (const document of files) {
+        if (owned?.has(document.revision)) continue;
+        await writeAtomic2(
+          revisionFile(snapshot.handle, document.revision),
+          document.text
+        );
+        claim(snapshot.handle, document.revision);
+      }
+      const meta = {
+        schema: SCHEMA_VERSION,
+        handle: snapshot.handle,
+        format: snapshot.format,
+        revision: snapshot.head.revision,
+        bytes: snapshot.head.bytes,
+        createdAt: snapshot.createdAt,
+        updatedAt: snapshot.updatedAt,
+        ...snapshot.title !== void 0 && { title: snapshot.title },
+        pinnedRevisions: pinned.sort((a, b) => a - b)
+      };
+      await writeAtomic2(path6.join(dir, META_FILE), JSON.stringify(meta));
+      await pruneRevisions(snapshot.handle, retained);
+    },
+    async list() {
+      const handles = await handleDirs();
+      const metas = await Promise.all(
+        handles.map((handle) => readMeta(handle))
+      );
+      return metas.filter((meta) => meta !== void 0).sort((a, b) => b.updatedAt - a.updatedAt);
+    },
+    async load(handle) {
+      if (!isPersistableHandle(handle)) return void 0;
+      const meta = await readMeta(handle);
+      if (!meta) return void 0;
+      const head = await readRevision(handle, meta.revision);
+      if (!head) {
+        await fs7.rm(dirFor(handle), { recursive: true, force: true }).catch(() => void 0);
+        return void 0;
+      }
+      const pins = [];
+      for (const revision of meta.pinnedRevisions) {
+        const pin = await readRevision(handle, revision);
+        if (pin) pins.push(pin);
+      }
+      return {
+        ...meta,
+        // A pin whose file went missing is dropped rather than advertised: the
+        // record has to describe what can actually be read back.
+        pinnedRevisions: pins.map((pin) => pin.revision).sort((a, b) => a - b),
+        head,
+        pins
+      };
+    },
+    async remove(handle) {
+      if (!isPersistableHandle(handle)) return false;
+      const dir = dirFor(handle);
+      if (!await exists(dir)) {
+        authored.delete(handle);
+        return false;
+      }
+      await fs7.rm(dir, { recursive: true, force: true });
+      authored.delete(handle);
+      return true;
+    }
+  };
+}
+async function exists(target) {
+  try {
+    await fs7.stat(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function isStale(target) {
+  try {
+    const { mtimeMs } = await fs7.stat(target);
+    return Date.now() - mtimeMs > STALE_TEMP_MS;
+  } catch {
+    return false;
+  }
+}
+function revisionOf(name) {
+  if (!name.startsWith(REVISION_PREFIX) || !name.endsWith(REVISION_SUFFIX)) {
+    return void 0;
+  }
+  const digits = name.slice(
+    REVISION_PREFIX.length,
+    name.length - REVISION_SUFFIX.length
+  );
+  if (!/^[0-9]+$/.test(digits)) return void 0;
+  return Number(digits);
+}
+function parseMeta(raw, handle) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return void 0;
+  }
+  const meta = parsed;
+  if (meta.schema !== SCHEMA_VERSION) return void 0;
+  if (meta.handle !== handle) return void 0;
+  if (!FORMAT_NAMES.includes(meta.format)) return void 0;
+  if (!isPositiveInteger(meta.revision)) return void 0;
+  if (!isNonNegativeInteger(meta.bytes)) return void 0;
+  if (!isNonNegativeInteger(meta.createdAt)) return void 0;
+  if (!isNonNegativeInteger(meta.updatedAt)) return void 0;
+  if (meta.title !== void 0 && typeof meta.title !== "string")
+    return void 0;
+  const pinnedRevisions = Array.isArray(meta.pinnedRevisions) ? meta.pinnedRevisions.filter(isPositiveInteger) : [];
+  return {
+    handle,
+    format: meta.format,
+    revision: meta.revision,
+    bytes: meta.bytes,
+    createdAt: meta.createdAt,
+    updatedAt: meta.updatedAt,
+    ...typeof meta.title === "string" && { title: meta.title },
+    pinnedRevisions: [...pinnedRevisions].sort((a, b) => a - b)
+  };
+}
+function isPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+// src/workspace/store.ts
 var WORKSPACE_ERROR_CODES = {
   EVICTED: "E_WORKSPACE_EVICTED",
   LIMIT: "E_WORKSPACE_LIMIT",
   DOCUMENT_TOO_LARGE: "E_DOCUMENT_TOO_LARGE",
-  INVALID_ROOT: "E_INVALID_DOCUMENT_ROOT"
+  INVALID_ROOT: "E_INVALID_DOCUMENT_ROOT",
+  /**
+   * A revision could not be mirrored to disk (#290). A warning, never a
+   * failure: the edit landed and the workspace is usable, but this connection
+   * has stopped being survivable and saying so is the whole point.
+   */
+  NOT_PERSISTED: "W_WORKSPACE_NOT_PERSISTED",
+  /**
+   * A close could not delete the durable copy, so nothing was released (#290).
+   * An error rather than a warning: the agent asked for the document to be
+   * destroyed, and it is still there to be read by the next connection.
+   */
+  NOT_CLOSED: "E_WORKSPACE_NOT_CLOSED"
 };
 var DEFAULT_WORKSPACE_LIMITS = {
   maxWorkspaces: 16,
@@ -5052,6 +5390,7 @@ function createMemoryWorkspaceStore(options = {}) {
   };
   const now = options.now ?? Date.now;
   const newHandle = options.newHandle ?? defaultHandle;
+  const persistence = options.persistence;
   const entries = /* @__PURE__ */ new Map();
   const tombstones = /* @__PURE__ */ new Map();
   function footprint(entry) {
@@ -5064,12 +5403,8 @@ function createMemoryWorkspaceStore(options = {}) {
     for (const entry of entries.values()) total += footprint(entry);
     return total;
   }
-  function tombstone(entry, reason) {
-    tombstones.set(entry.handle, {
-      reason,
-      at: now(),
-      revision: entry.revision
-    });
+  function tombstone(handle, reason, revision) {
+    tombstones.set(handle, { reason, at: now(), revision });
     while (tombstones.size > MAX_TOMBSTONES) {
       const oldest = tombstones.keys().next();
       if (oldest.done) break;
@@ -5079,7 +5414,7 @@ function createMemoryWorkspaceStore(options = {}) {
   function evict(entry, reason) {
     entries.delete(entry.handle);
     tombstones.delete(entry.handle);
-    tombstone(entry, reason);
+    tombstone(entry.handle, reason, entry.revision);
   }
   function sweep() {
     const at = now();
@@ -5087,6 +5422,108 @@ function createMemoryWorkspaceStore(options = {}) {
       if (at - entry.touchedAt > limits.idleTtlMs) evict(entry, "ttl");
     }
   }
+  async function persist(entry) {
+    if (!persistence) return void 0;
+    try {
+      await persistence.save({
+        handle: entry.handle,
+        format: entry.format,
+        createdAt: entry.createdAt,
+        updatedAt: entry.updatedAt,
+        ...entry.title !== void 0 && { title: entry.title },
+        head: {
+          revision: entry.revision,
+          text: entry.text,
+          bytes: entry.bytes
+        },
+        pins: [...entry.pins.entries()].map(([revision, pin]) => ({
+          revision,
+          text: pin.text,
+          bytes: pin.bytes
+        }))
+      });
+      entry.persisted = true;
+      return void 0;
+    } catch (error) {
+      entry.persisted = false;
+      return diagnostic(
+        WORKSPACE_ERROR_CODES.NOT_PERSISTED,
+        `Revision ${entry.revision} of ${entry.handle} is held in memory but was not written to ${persistence.root}: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          severity: "warning",
+          suggestion: "Export the JSON with jto_workspace_snapshot and keep it yourself; this handle will not survive a lost connection.",
+          context: {
+            handle: entry.handle,
+            revision: entry.revision,
+            workspaceRoot: persistence.root
+          }
+        }
+      );
+    }
+  }
+  function committed(record, warning) {
+    return { ok: true, record, ...warning && { warnings: [warning] } };
+  }
+  async function rehydrate(handle) {
+    if (!persistence || !isPersistableHandle(handle)) return void 0;
+    let loaded;
+    try {
+      loaded = await persistence.load(handle);
+    } catch {
+      return void 0;
+    }
+    if (!loaded) return void 0;
+    const restored = loaded;
+    const pins = [...restored.pins].sort((a, b) => b.revision - a.revision).slice(0, limits.maxPinnedRevisions);
+    const needed = pins.reduce(
+      (total, pin) => total + pin.bytes,
+      restored.head.bytes
+    );
+    if (restored.head.bytes > limits.maxDocumentBytes) {
+      return tooLarge(restored.head.bytes, limits.maxDocumentBytes);
+    }
+    if (!hasRoom(needed, true)) {
+      return failure(
+        WORKSPACE_ERROR_CODES.LIMIT,
+        `Workspace ${handle} is on disk at revision ${restored.revision} but does not fit in this connection's ${limits.maxTotalBytes}-byte budget.`,
+        {
+          suggestion: "Close a workspace you have finished with, then use this handle again.",
+          context: {
+            handle,
+            bytes: needed,
+            maxTotalBytes: limits.maxTotalBytes,
+            maxWorkspaces: limits.maxWorkspaces
+          }
+        }
+      );
+    }
+    const entry = {
+      handle,
+      format: restored.format,
+      revision: restored.head.revision,
+      text: restored.head.text,
+      bytes: restored.head.bytes,
+      createdAt: restored.createdAt,
+      updatedAt: restored.updatedAt,
+      touchedAt: now(),
+      ...restored.title !== void 0 && { title: restored.title },
+      pins: new Map(
+        pins.map((pin) => [pin.revision, { text: pin.text, bytes: pin.bytes }])
+      ),
+      persisted: true
+    };
+    entries.set(handle, entry);
+    tombstones.delete(handle);
+    return { ok: true, entry };
+  }
+  async function resolve3(handle) {
+    const entry = entries.get(handle);
+    if (entry) return { entry };
+    const restored = await rehydrate(handle);
+    if (restored === void 0) return missing(handle);
+    if (!restored.ok) return restored;
+    return { entry: restored.entry };
+  }
   function missing(handle) {
     const grave = tombstones.get(handle);
     if (grave?.reason === "ttl") {
@@ -5122,12 +5559,29 @@ function createMemoryWorkspaceStore(options = {}) {
       createdAt: new Date(entry.createdAt).toISOString(),
       updatedAt: new Date(entry.updatedAt).toISOString(),
       ...entry.title !== void 0 && { title: entry.title },
-      pinnedRevisions: [...entry.pins.keys()].sort((a, b) => a - b)
+      pinnedRevisions: [...entry.pins.keys()].sort((a, b) => a - b),
+      ...persistence && { persisted: entry.persisted }
+    };
+  }
+  function fromMeta(meta) {
+    return {
+      handle: meta.handle,
+      format: meta.format,
+      revision: meta.revision,
+      bytes: meta.bytes,
+      createdAt: new Date(meta.createdAt).toISOString(),
+      updatedAt: new Date(meta.updatedAt).toISOString(),
+      ...meta.title !== void 0 && { title: meta.title },
+      pinnedRevisions: [...meta.pinnedRevisions],
+      persisted: true
     };
   }
   return {
     available: true,
     limits,
+    ...persistence && {
+      persistence: { root: persistence.root, limits: persistence.limits }
+    },
     usage() {
       sweep();
       return { workspaces: entries.size, bytes: totalBytes() };
@@ -5168,15 +5622,18 @@ function createMemoryWorkspaceStore(options = {}) {
         updatedAt: at,
         touchedAt: at,
         ...input.title !== void 0 && { title: input.title },
-        pins: /* @__PURE__ */ new Map()
+        pins: /* @__PURE__ */ new Map(),
+        persisted: false
       };
       entries.set(entry.handle, entry);
-      return { ok: true, record: toRecord(entry) };
+      const warning = await persist(entry);
+      return committed(toRecord(entry), warning);
     },
     async get(handle, readOptions) {
       sweep();
-      const entry = entries.get(handle);
-      if (!entry) return missing(handle);
+      const found = await resolve3(handle);
+      if (!("entry" in found)) return found;
+      const entry = found.entry;
       entry.touchedAt = now();
       let text = entry.text;
       let bytes = entry.bytes;
@@ -5201,15 +5658,16 @@ function createMemoryWorkspaceStore(options = {}) {
             context: { handle, pointer }
           });
         }
-        const found = resolvePointer(document, parsed.tokens);
-        if (found.found) projection[pointer] = found.value;
+        const found2 = resolvePointer(document, parsed.tokens);
+        if (found2.found) projection[pointer] = found2.value;
       }
       return { ok: true, record, document, projection };
     },
     async patch(input) {
       sweep();
-      const entry = entries.get(input.handle);
-      if (!entry) return missing(input.handle);
+      const found = await resolve3(input.handle);
+      if (!("entry" in found)) return found;
+      const entry = found.entry;
       entry.touchedAt = now();
       if (input.baseRevision !== void 0 && input.baseRevision !== entry.revision) {
         return stale(
@@ -5275,12 +5733,14 @@ function createMemoryWorkspaceStore(options = {}) {
       entry.revision += 1;
       entry.updatedAt = now();
       entry.touchedAt = entry.updatedAt;
-      return { ok: true, record: toRecord(entry) };
+      const warning = await persist(entry);
+      return committed(toRecord(entry), warning);
     },
     async snapshot(handle) {
       sweep();
-      const entry = entries.get(handle);
-      if (!entry) return missing(handle);
+      const found = await resolve3(handle);
+      if (!("entry" in found)) return found;
+      const entry = found.entry;
       entry.touchedAt = now();
       const revision = entry.revision;
       const document = JSON.parse(entry.text);
@@ -5289,24 +5749,70 @@ function createMemoryWorkspaceStore(options = {}) {
           entry.pins.set(revision, { text: entry.text, bytes: entry.bytes });
         }
       }
-      return { ok: true, record: toRecord(entry), document };
-    },
-    async list() {
-      sweep();
+      const warning = entry.pins.has(revision) ? await persist(entry) : void 0;
       return {
         ok: true,
-        records: [...entries.values()].map((entry) => toRecord(entry))
+        record: toRecord(entry),
+        document,
+        ...warning && { warnings: [warning] }
       };
     },
+    async list() {
+      sweep();
+      const records = [...entries.values()].map((entry) => toRecord(entry));
+      if (!persistence) return { ok: true, records };
+      const resident = new Set(records.map((record) => record.handle));
+      let stored = [];
+      try {
+        stored = await persistence.list();
+      } catch {
+      }
+      for (const meta of stored) {
+        if (resident.has(meta.handle)) continue;
+        if (tombstones.get(meta.handle)?.reason === "closed") continue;
+        records.push(fromMeta(meta));
+      }
+      return { ok: true, records };
+    },
     async close(handle) {
       sweep();
       const entry = entries.get(handle);
-      if (!entry) return { ok: true, handle, closed: false };
-      evict(entry, "closed");
-      return { ok: true, handle, closed: true };
+      let durable = false;
+      if (persistence) {
+        try {
+          durable = await persistence.remove(handle);
+        } catch (error) {
+          return failure(
+            WORKSPACE_ERROR_CODES.NOT_CLOSED,
+            `Workspace ${handle} could not be removed from ${persistence.root}: ${error instanceof Error ? error.message : String(error)}. It is still open and still on disk.`,
+            {
+              suggestion: "Check the workspace directory is writable, then close again.",
+              context: { handle, workspaceRoot: persistence.root }
+            }
+          );
+        }
+      }
+      if (entry) evict(entry, "closed");
+      else if (durable) tombstone(handle, "closed", 0);
+      return { ok: true, handle, closed: entry !== void 0 || durable };
     },
+    /**
+     * Release memory, keep the disk.
+     *
+     * The asymmetry with `close` is the point: this exists for a host
+     * reclaiming memory at a moment of its own choosing, and #290 is precisely
+     * about an event that ends a connection not being allowed to destroy
+     * revisions. The handles come back from disk on next use.
+     */
     async closeAll() {
-      for (const entry of [...entries.values()]) evict(entry, "closed");
+      for (const entry of [...entries.values()]) {
+        if (!persistence) {
+          evict(entry, "closed");
+          continue;
+        }
+        entries.delete(entry.handle);
+        tombstones.delete(entry.handle);
+      }
     }
   };
   function stale(entry, wanted, pinned, mutation = false) {
@@ -5326,7 +5832,7 @@ function createMemoryWorkspaceStore(options = {}) {
   }
 }
 function defaultHandle() {
-  return `ws_${randomBytes2(9).toString("base64url")}`;
+  return `ws_${randomBytes3(9).toString("base64url")}`;
 }
 function serialize(document) {
   let text;
@@ -5379,7 +5885,7 @@ var workspaceSchema = {
   properties: {
     handle: {
       type: "string",
-      description: "Opaque, valid only on this connection."
+      description: "Opaque and server-generated. Valid only on this connection, unless the server has a workspace directory \u2014 then it survives a reconnect and jto_workspace_list hands it back."
     },
     format: { type: "string", enum: [...FORMAT_NAMES] },
     revision: {
@@ -5397,6 +5903,10 @@ var workspaceSchema = {
       type: "array",
       items: { type: "integer" },
       description: "Revisions kept retrievable by jto_workspace_snapshot; read one back with `revision`."
+    },
+    persisted: {
+      type: "boolean",
+      description: "True when this revision is mirrored to disk and so survives a lost connection. Absent when this connection has no workspace directory configured."
     }
   },
   required: [
@@ -5410,6 +5920,26 @@ var workspaceSchema = {
   ],
   additionalProperties: false
 };
+var persistenceSchema = {
+  type: "object",
+  description: "Where revisions survive the connection. Absent when workspaces are memory-only, which is the default.",
+  properties: {
+    root: { type: "string" },
+    maxWorkspaces: { type: "integer" },
+    maxRevisionsPerWorkspace: {
+      type: "integer",
+      description: "Revision files kept per handle: the head plus its pins."
+    },
+    maxEntryBytes: { type: "integer" }
+  },
+  required: [
+    "root",
+    "maxWorkspaces",
+    "maxRevisionsPerWorkspace",
+    "maxEntryBytes"
+  ],
+  additionalProperties: false
+};
 var limitsSchema = {
   type: "object",
   description: "What this connection allows. Bounded on purpose; see the codes above.",
@@ -5441,7 +5971,9 @@ function isMemoryStore(store) {
 }
 function ensureStore(deps) {
   if (deps.workspaces().available || hasWorkspaceStore()) return;
-  const owned = createMemoryWorkspaceStore();
+  const owned = createMemoryWorkspaceStore(
+    deps.workspacePersistence ? { persistence: deps.workspacePersistence } : {}
+  );
   deps.workspaces = () => owned;
 }
 function register8(server, deps) {
@@ -5484,9 +6016,9 @@ function register8(server, deps) {
           ...args.title !== void 0 && { title: args.title }
         });
         if (!created.ok) return created;
-        return success(
-          { workspace: created.record },
-          seeded ? [
+        return success({ workspace: created.record }, [
+          ...created.warnings ?? [],
+          ...seeded ? [
             diagnostic(
               "W_BLANK_DOCUMENT",
               `Opened an empty ${args.format} skeleton; it has no content until you patch some in.`,
@@ -5496,7 +6028,7 @@ function register8(server, deps) {
               }
             )
           ] : []
-        );
+        ]);
       })
     )
   );
@@ -5562,17 +6094,20 @@ function register8(server, deps) {
         const missingPaths = projecting ? args.paths.filter(
           (pointer) => !(pointer in projection)
         ) : [];
-        const diagnostics = missingPaths.map(
-          (pointer) => diagnostic(
-            "W_PATH_NOT_FOUND",
-            `${pointer} does not resolve in revision ${read.record.revision}.`,
-            {
-              severity: "warning",
-              path: pointer,
-              suggestion: "Read a shorter prefix of the pointer to see what is actually there."
-            }
+        const diagnostics = [
+          ...read.warnings ?? [],
+          ...missingPaths.map(
+            (pointer) => diagnostic(
+              "W_PATH_NOT_FOUND",
+              `${pointer} does not resolve in revision ${read.record.revision}.`,
+              {
+                severity: "warning",
+                path: pointer,
+                suggestion: "Read a shorter prefix of the pointer to see what is actually there."
+              }
+            )
           )
-        );
+        ];
         return success(
           {
             workspace: read.record,
@@ -5641,7 +6176,7 @@ function register8(server, deps) {
           }
         });
         if (!patched.ok) return patched;
-        return success({ workspace: patched.record });
+        return success({ workspace: patched.record }, patched.warnings ?? []);
       })
     )
   );
@@ -5687,7 +6222,7 @@ function register8(server, deps) {
       await guarded(async () => {
         const snapshot = await deps.workspaces().snapshot(args.handle);
         if (!snapshot.ok) return snapshot;
-        const diagnostics = [];
+        const diagnostics = [...snapshot.warnings ?? []];
         if (!snapshot.record.pinnedRevisions.includes(snapshot.record.revision)) {
           diagnostics.push(
             diagnostic(
@@ -5730,7 +6265,7 @@ function register8(server, deps) {
     "jto_workspace_list",
     {
       title: "List open workspaces",
-      description: "Every document open on this connection, with its revision and size. Call this to recover handles you no longer have \u2014 it is the cheapest way back after losing track of what you opened. An empty list means nothing is open, not that anything failed.",
+      description: "Every document open on this connection, with its revision and size. Call this to recover handles you no longer have \u2014 it is the cheapest way back after losing track of what you opened, including after a reconnect when the server has a workspace directory. An empty list means nothing is open, not that anything failed.",
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: S({
         type: "object",
@@ -5745,6 +6280,7 @@ function register8(server, deps) {
             description: "False when this connection has workspaces switched off."
           },
           limits: limitsSchema,
+          persistence: persistenceSchema,
           usage: {
             type: "object",
             properties: {
@@ -5762,12 +6298,24 @@ function register8(server, deps) {
         const store = deps.workspaces();
         const listed = await store.list();
         if (!listed.ok) return listed;
-        const budget = isMemoryStore(store) ? { limits: store.limits, usage: store.usage() } : {};
-        return success({
-          workspaces: listed.records,
-          available: store.available,
-          ...budget
-        });
+        const budget = isMemoryStore(store) ? {
+          limits: store.limits,
+          usage: store.usage(),
+          ...store.persistence && {
+            persistence: {
+              root: store.persistence.root,
+              ...store.persistence.limits
+            }
+          }
+        } : {};
+        return success(
+          {
+            workspaces: listed.records,
+            available: store.available,
+            ...budget
+          },
+          listed.warnings ?? []
+        );
       })
     )
   );
@@ -5775,7 +6323,7 @@ function register8(server, deps) {
     "jto_workspace_close",
     {
       title: "Close a workspace",
-      description: "Release a handle and the memory behind it, including its pinned snapshots. Idempotent: closing a handle that is already gone reports `closed: false` rather than failing. Snapshot anything you still want first \u2014 closing is not recoverable.",
+      description: "Release a handle and everything behind it \u2014 the document, its pinned snapshots, and the durable copy when this connection keeps one. Idempotent: closing a handle that is already gone reports `closed: false` rather than failing. Snapshot anything you still want first \u2014 closing is not recoverable.",
       annotations: {
         readOnlyHint: false,
         destructiveHint: true,
@@ -5992,6 +6540,12 @@ function createServerFactory(deps) {
 
 // src/lib/deps.ts
 function createToolDeps(options = {}) {
+  const workspacePersistence = options.workspacePersistence ?? createWorkspacePersistence({
+    ...options.workspaceDir !== void 0 && {
+      flagDir: options.workspaceDir
+    },
+    ...options.env !== void 0 && { env: options.env }
+  });
   return {
     serverVersion: options.serverVersion ?? SERVER_VERSION,
     outputRoot: options.outputRoot ?? createOutputRoot({
@@ -6000,23 +6554,45 @@ function createToolDeps(options = {}) {
     }),
     getAdapter: options.getAdapter ?? getAdapter,
     workspaces: options.workspaces ?? getWorkspaceStore,
+    ...workspacePersistence !== void 0 && { workspacePersistence },
     maxInlineArtifactBytes: options.maxInlineArtifactBytes ?? MAX_INLINE_ARTIFACT_BYTES
   };
 }
 
 // src/cli.ts
+function takeValue(argv, index) {
+  const next = argv[index];
+  if (next === void 0 || next.startsWith("-") || next.trim() === "") {
+    return void 0;
+  }
+  return { value: next };
+}
 function parseArgs(argv) {
-  const parsed = { version: false, help: false, unknown: [] };
+  const parsed = {
+    version: false,
+    help: false,
+    unknown: [],
+    missingValue: []
+  };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === "--version" || arg === "-v") {
       parsed.version = true;
     } else if (arg === "--help" || arg === "-h") {
       parsed.help = true;
-    } else if (arg === "--output-dir") {
-      parsed.outputDir = argv[++index];
+    } else if (arg === "--output-dir" || arg === "--workspace-dir") {
+      const taken = takeValue(argv, index + 1);
+      if (!taken) {
+        parsed.missingValue.push(arg);
+        continue;
+      }
+      index += 1;
+      if (arg === "--output-dir") parsed.outputDir = taken.value;
+      else parsed.workspaceDir = taken.value;
     } else if (arg.startsWith("--output-dir=")) {
       parsed.outputDir = arg.slice("--output-dir=".length);
+    } else if (arg.startsWith("--workspace-dir=")) {
+      parsed.workspaceDir = arg.slice("--workspace-dir=".length);
     } else {
       parsed.unknown.push(arg);
     }
@@ -6034,11 +6610,16 @@ Options:
   --output-dir <path>  Directory generated files are written to. Overrides
                        ${OUTPUT_DIR_ENV}. Defaults to a per-connection
                        directory under the system temp dir.
+  --workspace-dir <p>  Directory workspace revisions are mirrored to, so a lost
+                       client session does not destroy them. Overrides
+                       ${WORKSPACE_DIR_ENV}. Off by default:
+                       without it, handles live only in memory.
   -v, --version        Print the version and exit.
   -h, --help           Print this help and exit.
 
 Environment:
   ${OUTPUT_DIR_ENV}    Output root, when --output-dir is absent.
+  ${WORKSPACE_DIR_ENV} Workspace root, when --workspace-dir is absent.
   LIBREOFFICE_PATH      LibreOffice binary, for preview.
   PDFTOPPM_PATH         poppler pdftoppm binary, for preview.
 
@@ -6061,13 +6642,23 @@ function main(argv) {
     process.stderr.write(
       `jto-mcp: unknown argument ${args.unknown[0]}
 Run jto-mcp --help.
+`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (args.missingValue.length > 0) {
+    process.stderr.write(
+      `jto-mcp: ${args.missingValue[0]} needs a directory path.
+Run jto-mcp --help.
 `
     );
     process.exitCode = 1;
     return;
   }
   const deps = createToolDeps({
-    ...args.outputDir !== void 0 && { outputDir: args.outputDir }
+    ...args.outputDir !== void 0 && { outputDir: args.outputDir },
+    ...args.workspaceDir !== void 0 && { workspaceDir: args.workspaceDir }
   });
   const handle = serveStdio(createServerFactory(deps), {
     legacy: "serve",