mason-context 0.17.4 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.18.0 — 2026-09-16
+
+- Fix overlapping snapshot writes restoring old descriptions and deleted flows. Snapshot saves, verdicts, and partial writes share a per-checkout cross-process lock; reads, replacement, and consolidation cleanup stay within the protected operation.
+- Bind map verification to entry kind, content, and bounded source evidence through review tokens. Changed or deleted entries return conflicts; older calls without tokens request a fresh review without recording a verdict. Existing snapshot files remain compatible; callers must include the returned entry kind and review token to record a verdict. Restart all Mason MCP processes for a checkout after upgrading; older binaries do not honor the new snapshot lock.
+- Recheck saved map verification evidence on retrieval. Changed evidence reports stale verification; unavailable evidence and legacy verdicts without tokens report unknown. Preserve historical verdicts and failure reasons, including when reviewed local edits are reverted to a clean checkout.
+- Diagnose incomplete lock owners and interrupted recovery guards, document safe manual cleanup after writers stop, and cover both interruption windows with controlled process-termination tests.
+- Cover the reported overwrite with a controlled regression, exercise both call orders through one MCP session and separate processes, and test interrupted writers, contention, partial cleanup, and stale review evidence. Run the snapshot regressions in the existing macOS, Linux, and Windows distribution matrix before publishing.
+
+Run `mason upgrade` for standalone installations, or `npm install -g mason-context@0.18.0` for npm installations. Restart **every Mason MCP process** sharing a checkout after upgrading: older processes do not participate in the new snapshot lock. Existing decisions and snapshot files are preserved. Older snapshot verdicts remain visible but report unknown verification until reviewed again with an evidence token. Existing integrations do not need setup again.
+
 ## 0.17.4 — 2026-09-15
 
 - Share Git document/source inventories within each automation inspection, with a separate fresh inventory before publication. Batch module ignore checks by directory level and reuse only identical scoped history queries.

package/dist/mason-audit.js

@@ -234,6 +234,102 @@ var init_storage = __esm({
   }
 });
 
+// src/utils/store-lock.ts
+import fs3 from "fs/promises";
+import os from "os";
+async function lockDiagnostic(file) {
+  let reason;
+  try {
+    const owner = JSON.parse(await fs3.readFile(file, "utf8"));
+    if (!owner || typeof owner.host !== "string" || !Number.isInteger(owner.pid) || owner.pid <= 0) {
+      reason = "Lock owner data is incomplete or malformed.";
+    } else if (owner.host !== os.hostname()) {
+      reason = "The lock belongs to another host; its process cannot be checked locally.";
+    } else {
+      try {
+        process.kill(owner.pid, 0);
+        reason = `Local owner PID ${owner.pid} is still running.`;
+      } catch (error) {
+        reason = error.code === "ESRCH" ? `Local owner PID ${owner.pid} has exited, but lock recovery has not completed.` : `Local owner PID ${owner.pid} could not be checked.`;
+      }
+    }
+  } catch (error) {
+    reason = error instanceof SyntaxError ? "Lock owner data is incomplete or malformed." : "Lock owner data could not be read; the lock may have changed.";
+  }
+  if (await fs3.lstat(file + ".reclaim").then(() => true, () => false)) {
+    reason += " A recovery guard also needs inspection: " + file + ".reclaim.";
+  }
+  return reason + " Retry if a writer is active. For manual recovery, stop all Mason writers for this checkout, confirm they have exited (including other hosts), then remove only confirmed abandoned lock and lock.reclaim files. See docs/reference.md#snapshot-repairs-and-verification.";
+}
+async function withStoreLock(root, directory, run, waitMs = 5e3, label = "Mason store") {
+  const file = await storePath(root, directory + "/lock", true);
+  const deadline = Date.now() + waitMs;
+  let handle;
+  while (!handle) {
+    try {
+      handle = await fs3.open(file, "wx", 384);
+      try {
+        await handle.writeFile(JSON.stringify({ pid: process.pid, host: os.hostname() }));
+      } catch (error) {
+        await handle.close().catch(() => {
+        });
+        handle = void 0;
+        await fs3.rm(file, { force: true }).catch(() => {
+        });
+        throw error;
+      }
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      try {
+        const owner = JSON.parse(await fs3.readFile(file, "utf8"));
+        if (owner.host === os.hostname() && Number.isInteger(owner.pid) && owner.pid > 0) {
+          try {
+            process.kill(owner.pid, 0);
+          } catch (probe) {
+            if (probe.code === "ESRCH") {
+              const reclaim = file + ".reclaim";
+              let guard;
+              try {
+                guard = await fs3.open(reclaim, "wx", 384);
+                const current = JSON.parse(await fs3.readFile(file, "utf8"));
+                if (current.pid === owner.pid && current.host === owner.host) await fs3.unlink(file);
+              } finally {
+                if (guard) {
+                  await guard.close();
+                  await fs3.rm(reclaim, { force: true });
+                }
+              }
+            }
+          }
+        }
+      } catch {
+      }
+      if (Date.now() >= deadline) throw new Error(label + " is busy or its lock needs inspection: " + file + ". " + await lockDiagnostic(file));
+      await new Promise((resolve) => setTimeout(resolve, 40));
+    }
+  }
+  try {
+    return await run();
+  } finally {
+    await handle.close();
+    await fs3.unlink(file);
+  }
+}
+var init_store_lock = __esm({
+  "src/utils/store-lock.ts"() {
+    "use strict";
+    init_storage();
+  }
+});
+
+// src/snapshot/lock.ts
+var init_lock = __esm({
+  "src/snapshot/lock.ts"() {
+    "use strict";
+    init_store_lock();
+  }
+});
+
 // src/test-map.ts
 import path4 from "path";
 var init_test_map = __esm({
@@ -264,6 +360,7 @@ var init_snapshot = __esm({
     init_files();
     init_files();
     init_storage();
+    init_lock();
     init_paths();
     init_test_map();
     repoPath = z.string().refine((value) => normalizeRepoPath(value) !== null, "Expected a relative repository path");
@@ -271,6 +368,7 @@ var init_snapshot = __esm({
       refreshedHash: z.string().optional(),
       verifiedAt: z.string().optional(),
       verifiedHash: z.string().optional(),
+      verificationToken: z.string().optional(),
       verificationFailed: z.boolean().optional(),
       verificationNote: z.string().optional()
     };
@@ -294,7 +392,7 @@ var init_snapshot = __esm({
 });
 
 // src/drift/drift.ts
-import fs3 from "fs/promises";
+import fs4 from "fs/promises";
 import path6 from "path";
 function parseChanges(output) {
   const fields = output.split("\0");
@@ -855,12 +953,12 @@ var init_git = __esm({
 });
 
 // src/audit/inputs.ts
-import fs4 from "fs/promises";
+import fs5 from "fs/promises";
 import * as nativeFs from "fs";
 import path9 from "path";
 import fg2 from "fast-glob";
 async function auditInputPath(root, file) {
-  if (file === ".") return fs4.realpath(root);
+  if (file === ".") return fs5.realpath(root);
   try {
     return await storePath(root, file);
   } catch (error) {
@@ -965,7 +1063,7 @@ var init_inputs = __esm({
 });
 
 // src/audit/docs.ts
-import fs5 from "fs/promises";
+import fs6 from "fs/promises";
 import path10 from "path";
 import fg3 from "fast-glob";
 async function dirtyDocs(resolvedRoot, files) {
@@ -1037,7 +1135,7 @@ async function localDocPaths(root) {
   for (const dir of [".", ".claude"]) {
     let entries;
     try {
-      entries = await fs5.readdir(await auditInputPath(root, dir), { withFileTypes: true });
+      entries = await fs6.readdir(await auditInputPath(root, dir), { withFileTypes: true });
     } catch (error) {
       if (error.code === "ENOENT") continue;
       throw error;
@@ -1116,7 +1214,7 @@ var init_types = __esm({
 });
 
 // src/audit/scope.ts
-import fs6 from "fs/promises";
+import fs7 from "fs/promises";
 import path11 from "path";
 function scopedPath(directory, value) {
   if (path11.posix.isAbsolute(value) || value.includes("\\") || /[\x00-\x1f]/.test(value)) return null;
@@ -1136,7 +1234,7 @@ function pathClaimScope(doc, claim) {
 }
 async function pathExists(root, file) {
   try {
-    await fs6.access(await auditInputPath(root, file));
+    await fs7.access(await auditInputPath(root, file));
     return true;
   } catch (error) {
     if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) return false;
@@ -1226,7 +1324,7 @@ var init_deleted_reference = __esm({
 
 // src/audit/checks/new-module.ts
 import fg4 from "fast-glob";
-import fs7 from "fs/promises";
+import fs8 from "fs/promises";
 import path13 from "path";
 function escapeRegExp(text2) {
   return text2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1278,7 +1376,7 @@ async function collectModuleCandidates(root, combinedDocs) {
     const byParent = /* @__PURE__ */ new Map();
     for (let offset = 0; offset < parents.length; offset += 16) {
       await Promise.all(parents.slice(offset, offset + 16).map(async (dir) => {
-        const entries = await fs7.readdir(await auditInputPath(root, dir), { withFileTypes: true });
+        const entries = await fs8.readdir(await auditInputPath(root, dir), { withFileTypes: true });
         const dirs = entries.filter((entry) => (entry.isDirectory() || entry.isSymbolicLink() && sources.some((file) => file.startsWith(path13.posix.join(dir, entry.name) + "/"))) && !entry.name.startsWith(".") && !DIR_DENYLIST.has(entry.name)).map((entry) => path13.posix.join(dir, entry.name));
         byParent.set(dir, dirs);
       }));
@@ -1942,7 +2040,7 @@ var init_provenance = __esm({
 });
 
 // src/decisions/decisions.ts
-import fs8 from "fs/promises";
+import fs9 from "fs/promises";
 import path17 from "path";
 import { createHash } from "crypto";
 import { z as z3 } from "zod";
@@ -1951,7 +2049,7 @@ async function loadDecisionStore(rootDir) {
   const diagnostics = [];
   let entries;
   try {
-    entries = await fs8.readdir(await storePath(rootDir, ".mason/decisions"));
+    entries = await fs9.readdir(await storePath(rootDir, ".mason/decisions"));
   } catch (error) {
     if (error.code !== "ENOENT") diagnostics.push({ path: ".mason/decisions", message: String(error) });
     return { records, diagnostics };
@@ -2219,68 +2317,15 @@ var init_findings = __esm({
 });
 
 // src/automation/store.ts
-import fs9 from "fs/promises";
-import os from "os";
 import { z as z5 } from "zod";
-async function withLock(root, directory, run, waitMs = 5e3) {
-  const file = await storePath(root, directory + "/lock", true);
-  const deadline = Date.now() + waitMs;
-  let handle;
-  while (!handle) {
-    try {
-      handle = await fs9.open(file, "wx", 384);
-      try {
-        await handle.writeFile(JSON.stringify({ pid: process.pid, host: os.hostname() }));
-      } catch (error) {
-        await handle.close().catch(() => {
-        });
-        handle = void 0;
-        await fs9.rm(file, { force: true }).catch(() => {
-        });
-        throw error;
-      }
-    } catch (error) {
-      if (error.code !== "EEXIST") throw error;
-      try {
-        const owner = JSON.parse(await fs9.readFile(file, "utf8"));
-        if (owner.host === os.hostname() && Number.isInteger(owner.pid) && owner.pid > 0) {
-          try {
-            process.kill(owner.pid, 0);
-          } catch (probe) {
-            if (probe.code === "ESRCH") {
-              const reclaim = file + ".reclaim";
-              let guard;
-              try {
-                guard = await fs9.open(reclaim, "wx", 384);
-                const current = JSON.parse(await fs9.readFile(file, "utf8"));
-                if (current.pid === owner.pid && current.host === owner.host) await fs9.unlink(file);
-              } finally {
-                if (guard) {
-                  await guard.close();
-                  await fs9.rm(reclaim, { force: true });
-                }
-              }
-            }
-          }
-        }
-      } catch {
-      }
-      if (Date.now() >= deadline) throw new Error("Automation is busy or its lock needs inspection: " + file);
-      await new Promise((resolve) => setTimeout(resolve, 40));
-    }
-  }
-  try {
-    return await run();
-  } finally {
-    await handle.close();
-    await fs9.unlink(file);
-  }
+function withLock(root, directory, run, waitMs = 5e3) {
+  return withStoreLock(root, directory, run, waitMs, "Automation");
 }
 var hostSchema, stateSchema;
 var init_store = __esm({
   "src/automation/store.ts"() {
     "use strict";
-    init_storage();
+    init_store_lock();
     hostSchema = z5.enum(["claude", "codex"]);
     stateSchema = z5.object({
       version: z5.literal(1),