@json-to-office/mcp-server 1.4.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.4.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";
 
@@ -221,6 +221,8 @@ var ERROR_CODES = {
   HOST_NOTE: "W_HOST_NOTE",
   /** A generation warning the core raised without a code of its own. */
   GENERATION: "W_GENERATION",
+  /** A design-quality rule threw, so its whole class of findings is missing. */
+  QUALITY_RULE_ERROR: "W_QUALITY_RULE_ERROR",
   /** A required host binary (LibreOffice, poppler) is absent. */
   DEPENDENCY_MISSING: "E_DEPENDENCY_MISSING",
   /** The client cancelled the request. */
@@ -317,6 +319,25 @@ function toolResult(payload) {
   };
 }
 var HOST_DEPENDENCY_ERRORS = /* @__PURE__ */ new Set([RENDERER_DEPENDENCY_MISSING]);
+function qualityOptionDiagnostic(error) {
+  const code = qualityCallerCode(error);
+  if (code === void 0 || code === ERROR_CODES.INVALID_DOCUMENT) {
+    return void 0;
+  }
+  return diagnostic(
+    code,
+    error instanceof Error ? error.message : String(error)
+  );
+}
+function qualityCallerCode(error) {
+  const code = error?.code;
+  if (code === "QUALITY_PROFILE_INCOMPATIBLE")
+    return OPTION_ERROR_CODES.INVALID_QUALITY_PROFILE;
+  if (code === "QUALITY_POLICY_INVALID")
+    return OPTION_ERROR_CODES.INVALID_QUALITY_POLICY;
+  if (code === "QUALITY_GATE_FAILED") return ERROR_CODES.INVALID_DOCUMENT;
+  return void 0;
+}
 function stackAllowed() {
   const flag = process.env.JTO_MCP_DEBUG_STACKS;
   return flag === "1" || flag === "true";
@@ -367,7 +388,7 @@ async function guarded(body) {
     return withHostNotes(result, notes);
   } catch (error) {
     const message2 = error instanceof Error ? error.message : String(error);
-    const code = error instanceof Error && HOST_DEPENDENCY_ERRORS.has(error.name) ? ERROR_CODES.DEPENDENCY_MISSING : ERROR_CODES.INTERNAL;
+    const code = qualityCallerCode(error) ?? (error instanceof Error && HOST_DEPENDENCY_ERRORS.has(error.name) ? ERROR_CODES.DEPENDENCY_MISSING : ERROR_CODES.INTERNAL);
     return withHostNotes(
       failure(code, message2, {
         context: {
@@ -386,7 +407,11 @@ var OPTION_ERROR_CODES = {
   /** `themePath` is not a data-only JSON theme path. */
   INVALID_THEME_PATH: "E_INVALID_THEME_PATH",
   /** The tool does not support the requested format. */
-  UNSUPPORTED_FORMAT: "E_UNSUPPORTED_FORMAT"
+  UNSUPPORTED_FORMAT: "E_UNSUPPORTED_FORMAT",
+  /** `quality.profile` does not cover the format or renderer of this run. */
+  INVALID_QUALITY_PROFILE: "E_INVALID_QUALITY_PROFILE",
+  /** `quality.policy` sets a gate, severity or budget that is not a legal value. */
+  INVALID_QUALITY_POLICY: "E_INVALID_QUALITY_POLICY"
 };
 var DEFERRED_TO_COMPILER = /* @__PURE__ */ new Set([
   ERROR_CODES.UNSUPPORTED_RENDERER_FEATURE
@@ -395,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 "";
@@ -426,6 +451,34 @@ function validationDiagnostics(errors) {
     })
   );
 }
+function qualityAnalysisDiagnostics(analysis) {
+  return analysis.diagnostics.map((diagnostic2) => ({
+    source: diagnostic2.source,
+    ruleId: diagnostic2.ruleId,
+    category: diagnostic2.category,
+    certainty: diagnostic2.certainty,
+    severity: diagnostic2.severity,
+    code: diagnostic2.code,
+    message: diagnostic2.message,
+    path: diagnostic2.path,
+    blocking: diagnostic2.blocking,
+    ...diagnostic2.suggestion !== void 0 && {
+      suggestion: diagnostic2.suggestion
+    },
+    ...diagnostic2.context !== void 0 && {
+      context: { ...diagnostic2.context }
+    },
+    ...diagnostic2.relatedPaths !== void 0 && {
+      relatedPaths: diagnostic2.relatedPaths
+    },
+    ...diagnostic2.evidence !== void 0 && {
+      evidence: { ...diagnostic2.evidence }
+    },
+    ...diagnostic2.fixes !== void 0 && {
+      fixes: diagnostic2.fixes
+    }
+  }));
+}
 function looksLikeValidationErrors(value) {
   return Array.isArray(value) && value.length > 0 && value.every(
     (entry) => typeof entry === "object" && entry !== null && typeof entry.message === "string"
@@ -570,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,
@@ -614,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",
@@ -699,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: {
@@ -862,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,
@@ -1122,10 +1187,10 @@ var STARTERS = [
     id: "pptx-minimal",
     format: "pptx",
     title: "Minimal presentation",
-    description: "The smallest valid .pptx: root, one slide, one title text.",
+    description: "The smallest well-formed .pptx: root with a declared 16:9 canvas, one slide, one title text. The canvas stays: without it the renderer silently falls back to 4:3.",
     document: {
       name: "pptx",
-      props: { title: "Untitled deck" },
+      props: { title: "Untitled deck", slideWidth: 13.333, slideHeight: 7.5 },
       children: [
         {
           name: "slide",
@@ -1982,17 +2047,26 @@ function capDiagnostics(diagnostics, limit) {
   if (diagnostics.length <= limit)
     return { kept: diagnostics, truncated: false };
   const ordered = [...diagnostics].sort(
-    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
+    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || Number(b.blocking === true) - Number(a.blocking === true)
   );
   return { kept: ordered.slice(0, limit), truncated: true };
 }
+function ruleErrorDiagnostics(analysis) {
+  return analysis.ruleErrors.map(
+    (entry) => diagnostic(
+      ERROR_CODES.QUALITY_RULE_ERROR,
+      `Quality rule "${entry.ruleId}" failed: ${entry.message}`,
+      { severity: "warning", source: "quality", ruleId: entry.ruleId }
+    )
+  );
+}
 var DEFAULT_MAX_DIAGNOSTICS = 100;
 function register4(server, deps) {
   server.registerTool(
     "jto_validate",
     {
       title: "Validate a document",
-      description: "Check a document against its format schema and report every defect as a path-addressed diagnostic. Paths are RFC 6901 JSON Pointers into the document you passed, so they can be used directly as patch targets; codes are the stable `E_`/`W_` vocabulary, e.g. `E_REQUIRED_PROPERTY`, `E_UNEXPECTED_PROPERTY`, `E_TYPE_MISMATCH`, `E_UNKNOWN_COMPONENT`. `ok` mirrors the gate generation applies: schema and semantic errors block it \u2014 the semantic rules the published JSON Schema cannot state, such as a text component needing one of `text`/`runs`, are checked here and only here \u2014 while renderer-profile findings (code `W_UNSUPPORTED_RENDERER_FEATURE`) come back as warnings because the renderer, not the schema, has the last word on those. A broken document is a normal result with `ok: false`, never an error. A renderer whose backend is not installed on this host is reported here too, as a `E_DEPENDENCY_MISSING` warning \u2014 the document may be fine and the host merely incomplete.",
+      description: "Check a document against its format schema and report every defect as a path-addressed diagnostic. Paths are RFC 6901 JSON Pointers into the document you passed, so they can be used directly as patch targets; codes are the stable `E_`/`W_` vocabulary. `ok` mirrors generation: schema and semantic errors block; design-quality `W_QUALITY_*` findings advise by default and block only when `quality.policy.gate` requests it. A broken document is a normal result with `ok: false`, never a protocol error.",
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: S({
         type: "object",
@@ -2008,6 +2082,29 @@ function register4(server, deps) {
             minimum: 1,
             maximum: 1e3,
             description: `Cap on returned diagnostics (default ${DEFAULT_MAX_DIAGNOSTICS}). Errors are kept ahead of warnings when the cap bites.`
+          },
+          quality: {
+            type: "object",
+            description: "Optional design profile plus per-run enforcement policy.",
+            properties: {
+              profile: {
+                type: "object",
+                properties: { id: { type: "string", minLength: 1 } },
+                required: ["id"],
+                additionalProperties: true
+              },
+              policy: {
+                type: "object",
+                properties: {
+                  gate: {
+                    type: "string",
+                    enum: ["none", "error", "warning", "info"]
+                  }
+                },
+                additionalProperties: true
+              }
+            },
+            additionalProperties: false
           }
         },
         required: ["format"],
@@ -2038,7 +2135,11 @@ function register4(server, deps) {
           },
           truncated: {
             type: "boolean",
-            description: "`diagnostics` was capped by `maxDiagnostics`."
+            description: "`diagnostics` was capped, by `maxDiagnostics` or by the budget the quality policy set."
+          },
+          profileId: {
+            type: "string",
+            description: "The quality profile the design analysis ran under, when one applied."
           }
         })
       )
@@ -2058,24 +2159,52 @@ function register4(server, deps) {
           resolved.document,
           args.renderer
         );
-        const all = [
+        let analysis;
+        let qualityOption;
+        if (adapter.analyzeQuality) {
+          try {
+            analysis = await adapter.analyzeQuality(resolved.document, {
+              renderer: args.renderer,
+              quality: args.quality
+            });
+          } catch (error) {
+            const option = result.valid ? void 0 : qualityOptionDiagnostic(error);
+            if (!option) throw error;
+            qualityOption = option;
+          }
+        }
+        const structural = [
           ...validationDiagnostics(result.errors),
-          ...unavailable2 ? [unavailable2] : []
+          ...unavailable2 ? [unavailable2] : [],
+          ...qualityOption ? [qualityOption] : []
+        ];
+        const all = [
+          ...structural,
+          ...analysis ? [
+            ...qualityAnalysisDiagnostics(analysis),
+            ...ruleErrorDiagnostics(analysis)
+          ] : []
         ];
         const counts = countDiagnostics(all);
+        const blocked = countDiagnostics(structural).error > 0 || analysis?.blocked === true;
         const { kept, truncated } = capDiagnostics(
           all,
           args.maxDiagnostics ?? DEFAULT_MAX_DIAGNOSTICS
         );
         return {
-          ok: counts.error === 0,
+          ok: !blocked,
           diagnostics: kept,
-          valid: counts.error === 0,
+          valid: !blocked,
           format: args.format,
           ...args.renderer !== void 0 && { renderer: args.renderer },
           source: sourceSummary(resolved),
           counts,
-          truncated
+          // The engine caps its own list under a policy budget, so a report
+          // shortened there would otherwise come back reading complete.
+          truncated: truncated || analysis?.truncated === true,
+          ...analysis?.profileId !== void 0 && {
+            profileId: analysis.profileId
+          }
         };
       })
     )
@@ -3019,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 {
       }
     })
@@ -3051,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`;
   }
@@ -3124,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,
@@ -3149,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);
       }
     );
   });
@@ -3195,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 {
@@ -3230,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);
@@ -3319,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,
@@ -3330,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()
     );
   });
 }
@@ -3424,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],
@@ -3435,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);
       }
     );
   });
@@ -4550,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 "/".'
       });
@@ -4560,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) {
@@ -4910,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,
@@ -4935,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) {
@@ -4947,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;
@@ -4962,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();
@@ -4970,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") {
@@ -5005,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() };
@@ -5051,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;
@@ -5084,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(
@@ -5158,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);
@@ -5172,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) {
@@ -5209,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;
@@ -5262,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: {
@@ -5280,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: [
@@ -5293,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.",
@@ -5324,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) {
@@ -5367,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.`,
@@ -5379,7 +6028,7 @@ function register8(server, deps) {
               }
             )
           ] : []
-        );
+        ]);
       })
     )
   );
@@ -5445,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,
@@ -5524,7 +6176,7 @@ function register8(server, deps) {
           }
         });
         if (!patched.ok) return patched;
-        return success({ workspace: patched.record });
+        return success({ workspace: patched.record }, patched.warnings ?? []);
       })
     )
   );
@@ -5570,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(
@@ -5613,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",
@@ -5628,6 +6280,7 @@ function register8(server, deps) {
             description: "False when this connection has workspaces switched off."
           },
           limits: limitsSchema,
+          persistence: persistenceSchema,
           usage: {
             type: "object",
             properties: {
@@ -5645,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 ?? []
+        );
       })
     )
   );
@@ -5658,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,
@@ -5705,6 +6370,7 @@ var RESOURCE_URIS = {
   catalog: "jto://catalog",
   renderers: "jto://renderers",
   themes: "jto://themes",
+  themeValues: "jto://themes/values",
   templates: "jto://templates",
   documentSchema: (format) => `jto://schema/${format}/document`,
   themeSchema: (format) => `jto://schema/${format}/theme`
@@ -5756,7 +6422,7 @@ function register9(server, deps) {
     RESOURCE_URIS.themes,
     {
       title: "Built-in themes",
-      description: "Theme names shipped with each format, usable as a document\u2019s props.theme or as the tools\u2019 theme option.",
+      description: "Theme names shipped with each format, usable as a document\u2019s props.theme or as the tools\u2019 theme option. jto://themes/values carries what each name actually looks like.",
       mimeType: JSON_MIME
     },
     async (uri) => {
@@ -5769,6 +6435,33 @@ function register9(server, deps) {
       });
     }
   );
+  server.registerResource(
+    "theme-values",
+    RESOURCE_URIS.themeValues,
+    {
+      title: "Built-in theme values",
+      description: "The palette, fonts, style tables and component defaults behind every built-in theme name \u2014 what a document actually opts into with props.theme. A name alone cannot tell you whether a theme fits the brief; this can.",
+      mimeType: JSON_MIME
+    },
+    async (uri) => {
+      const formats = await Promise.all(
+        FORMAT_NAMES.map(async (format) => {
+          const adapter = deps.getAdapter(format);
+          let themes;
+          try {
+            themes = adapter.getBuiltinThemeValues ? await adapter.getBuiltinThemeValues() : adapter.getBuiltinThemes();
+          } catch {
+            themes = adapter.getBuiltinThemes();
+          }
+          return {
+            format,
+            themes
+          };
+        })
+      );
+      return jsonContents(uri, { formats });
+    }
+  );
   server.registerResource(
     "templates",
     RESOURCE_URIS.templates,
@@ -5817,6 +6510,7 @@ Working rules:
 - Discover before authoring. Call jto_info first, then jto_discover and jto_describe_component (or read the jto:// resources) for the components and renderer ids a format actually supports.
 - Make small edits. With a workspace handle, patch precisely (RFC 6902 over RFC 6901 paths) instead of resending the whole document; without one, change one region at a time.
 - Validate often. Run jto_validate after each edit rather than once at the end; diagnostics are path-addressed, so they map straight back onto the JSON you just changed.
+- Treat design findings as defects. Schema-valid is not well-designed: jto_validate also lints layout and legibility (W_QUALITY_* \u2014 undeclared slide canvas, text overflowing its box, overcrowded slides, table widths exceeding their section). These never block generation, but they almost always show in the rendered result \u2014 repair them like errors.
 - Preview when the answer is visual. jto_preview renders pages to PNG; use it whenever layout, overflow or fit is in question, not only before finishing.
 - Snapshot before risky changes. jto_workspace_snapshot pins the current revision so a restructuring you cannot cleanly undo is still recoverable.
 
@@ -5846,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({
@@ -5854,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);
     }
@@ -5888,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.
 
@@ -5915,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",