mason-context 0.17.4 → 0.18.0

package/dist/mason-mcp.js

@@ -1098,6 +1098,105 @@ var init_scope = __esm({
   }
 });
 
+// src/utils/store-lock.ts
+import fs6 from "fs/promises";
+import os from "os";
+async function lockDiagnostic(file) {
+  let reason2;
+  try {
+    const owner = JSON.parse(await fs6.readFile(file, "utf8"));
+    if (!owner || typeof owner.host !== "string" || !Number.isInteger(owner.pid) || owner.pid <= 0) {
+      reason2 = "Lock owner data is incomplete or malformed.";
+    } else if (owner.host !== os.hostname()) {
+      reason2 = "The lock belongs to another host; its process cannot be checked locally.";
+    } else {
+      try {
+        process.kill(owner.pid, 0);
+        reason2 = `Local owner PID ${owner.pid} is still running.`;
+      } catch (error) {
+        reason2 = 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) {
+    reason2 = error instanceof SyntaxError ? "Lock owner data is incomplete or malformed." : "Lock owner data could not be read; the lock may have changed.";
+  }
+  if (await fs6.lstat(file + ".reclaim").then(() => true, () => false)) {
+    reason2 += " A recovery guard also needs inspection: " + file + ".reclaim.";
+  }
+  return reason2 + " 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 fs6.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 fs6.rm(file, { force: true }).catch(() => {
+        });
+        throw error;
+      }
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      try {
+        const owner = JSON.parse(await fs6.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 fs6.open(reclaim, "wx", 384);
+                const current = JSON.parse(await fs6.readFile(file, "utf8"));
+                if (current.pid === owner.pid && current.host === owner.host) await fs6.unlink(file);
+              } finally {
+                if (guard) {
+                  await guard.close();
+                  await fs6.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((resolve2) => setTimeout(resolve2, 40));
+    }
+  }
+  try {
+    return await run();
+  } finally {
+    await handle.close();
+    await fs6.unlink(file);
+  }
+}
+var init_store_lock = __esm({
+  "src/utils/store-lock.ts"() {
+    "use strict";
+    init_storage();
+  }
+});
+
+// src/snapshot/lock.ts
+function withSnapshotWrite(root, run, waitMs = 5e3) {
+  return withStoreLock(root, ".mason/local/snapshot-write", run, waitMs, "Snapshot store");
+}
+var init_lock = __esm({
+  "src/snapshot/lock.ts"() {
+    "use strict";
+    init_store_lock();
+  }
+});
+
 // src/test-map.ts
 var test_map_exports = {};
 __export(test_map_exports, {
@@ -1203,8 +1302,15 @@ async function inspectSnapshot(rootDir) {
     }] };
   }
 }
-async function saveSnapshot(rootDir, snapshot) {
-  await writeStoreJson(rootDir, ".mason/snapshot.json", snapshotSchema.parse(snapshot));
+async function updateSnapshot(rootDir, update) {
+  return withSnapshotWrite(rootDir, async () => {
+    const change = await update(await loadSnapshot(rootDir));
+    if (change.snapshot) {
+      await writeStoreJson(rootDir, ".mason/snapshot.json", snapshotSchema.parse(change.snapshot));
+      await change.afterSave?.();
+    }
+    return change.result;
+  });
 }
 async function getCurrentGitHash(rootDir) {
   try {
@@ -1277,6 +1383,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");
@@ -1284,6 +1391,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()
     };
@@ -1311,7 +1419,7 @@ var init_snapshot = __esm({
 });
 
 // src/drift/drift.ts
-import fs6 from "fs/promises";
+import fs7 from "fs/promises";
 import path11 from "path";
 function parseChanges(output) {
   const fields = output.split("\0");
@@ -1379,7 +1487,7 @@ async function findGhostFiles(resolvedRoot, mappedFiles) {
   const ghosts = [];
   for (const file of mappedFiles) {
     try {
-      await fs6.access(path11.join(resolvedRoot, file));
+      await fs7.access(path11.join(resolvedRoot, file));
     } catch {
       ghosts.push(file);
     }
@@ -1561,7 +1669,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, "\\$&");
@@ -1613,7 +1721,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);
       }));
@@ -2236,7 +2344,9 @@ function assessTrust(entry, freshness) {
 }
 function trustHint(states) {
   const parts = [];
-  if (states.some((s) => s.verification === "failed")) parts.push("Verification failed for returned entries; do not rely on those descriptions until corrected.");
+  if (states.some((s) => s.verification === "failed" || s.recordedVerdict === "failed")) parts.push("Verification failed for returned entries; do not rely on those descriptions until corrected.");
+  if (states.some((s) => s.verification === "stale")) parts.push("Recorded verification evidence changed; use verify_snapshot and review the current evidence before reusing those verdicts.");
+  if (states.some((s) => s.verification === "unknown")) parts.push("Recorded verification evidence cannot be confirmed; inspect the files and obtain a fresh review before relying on those verdicts.");
   if (states.some((s) => s.freshness === "unknown")) parts.push("Freshness is unknown for some returned entries; inspect their files before relying on them.");
   if (states.some((s) => s.freshness === "changed")) parts.push("Some returned entries have changed files, including possible local edits; verify against the current code.");
   if (!parts.length) parts.push("No changes detected in the returned anchors. This does not prove the descriptions are correct.");
@@ -2461,7 +2571,7 @@ __export(decisions_exports, {
   upsertDecision: () => upsertDecision,
   withDecisionWrite: () => withDecisionWrite
 });
-import fs8 from "fs/promises";
+import fs9 from "fs/promises";
 import path17 from "path";
 import { createHash } from "crypto";
 import { z as z3 } from "zod";
@@ -2470,7 +2580,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 };
@@ -2529,7 +2639,7 @@ async function withDecisionWrite(root, operation) {
   const lockPath = await storePath(root, ".mason/decisions/.write-lock", true);
   let lock;
   try {
-    lock = await fs8.open(lockPath, "wx", 384);
+    lock = await fs9.open(lockPath, "wx", 384);
   } catch (error) {
     if (error.code === "EEXIST") return { status: "error", error: "Decision store is locked by another write. Retry after it finishes; an abandoned .mason/decisions/.write-lock must be removed only after confirming no writer is running." };
     throw error;
@@ -2538,7 +2648,7 @@ async function withDecisionWrite(root, operation) {
     return await operation();
   } finally {
     await lock.close();
-    await fs8.unlink(lockPath);
+    await fs9.unlink(lockPath);
   }
 }
 async function upsertDecision(rootDir, input) {
@@ -2560,7 +2670,7 @@ async function upsertDecision(rootDir, input) {
     if (input.files && files.length < input.files.length) warnings.push("some anchor paths were outside the repo or duplicated and were dropped");
     for (const file of files) {
       try {
-        await fs8.access(path17.join(rootDir, file));
+        await fs9.access(path17.join(rootDir, file));
       } catch {
         warnings.push(`anchor file does not exist on disk: ${file}`);
       }
@@ -2910,8 +3020,6 @@ var init_findings = __esm({
 });
 
 // src/automation/store.ts
-import fs9 from "fs/promises";
-import os from "os";
 import { z as z5 } from "zod";
 function parseState(raw) {
   try {
@@ -2920,65 +3028,14 @@ function parseState(raw) {
     throw new Error("Invalid automation state; original evidence was retained.", { cause: error });
   }
 }
-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((resolve2) => setTimeout(resolve2, 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, events, stateSchema;
 var init_store = __esm({
   "src/automation/store.ts"() {
     "use strict";
-    init_storage();
+    init_store_lock();
     hostSchema = z5.enum(["claude", "codex"]);
     events = ["session_start", "turn_start", "before_tool", "after_tool", "task_end"];
     stateSchema = z5.object({
@@ -3761,7 +3818,7 @@ var init_evidence = __esm({
     init_dead_command();
     init_storage();
     init_advisory_review();
-    engineVersion = true ? "0.17.4" : "development";
+    engineVersion = true ? "0.18.0" : "development";
     hash = (value) => createHash3("sha256").update(JSON.stringify(value)).digest("hex");
     content = readAuditInput;
     cacheSchema = z8.object({ version: z8.literal(1), entries: z8.record(z8.object({ key: z8.string(), result: checkResultSchema })), digest: z8.string() });
@@ -3853,12 +3910,124 @@ var init_launcher = __esm({
     "use strict";
     init_evidence();
     init_model();
-    executingVersion = () => true ? "0.17.4" : "development";
+    executingVersion = () => true ? "0.18.0" : "development";
     mcpCommand = (host) => globalCommand(["--setup-host", host, "mcp"]);
     hookCommand = (host) => `mason --setup-host ${host} auto`;
   }
 });
 
+// src/snapshot/review.ts
+import { createHash as createHash5 } from "crypto";
+function snapshotEntryContent(entry) {
+  return {
+    description: entry.description,
+    files: "files" in entry ? entry.files : void 0,
+    chain: "chain" in entry ? entry.chain : void 0,
+    tests: "files" in entry ? entry.tests : void 0,
+    type: "files" in entry ? normalizeFeatureType(entry.type) : void 0
+  };
+}
+function reviewToken(kind, name, entry, evidence) {
+  return createHash5("sha256").update(JSON.stringify({
+    version: 1,
+    kind,
+    name,
+    entry: snapshotEntryContent(entry),
+    evidence
+  })).digest("hex");
+}
+async function prepareSnapshotReview(access, kind, name, entry) {
+  const files = "files" in entry ? entry.files : entry.chain;
+  const evidence = [];
+  const skeletons = [];
+  for (const file of files.slice(0, VERIFY_MAX_FILES_PER_ENTRY)) {
+    const full = await access.read(file);
+    evidence.push({ path: file, hash: full ? sourceHash(full.content) : null });
+    skeletons.push(full ? { path: full.path, content: full.content.slice(0, VERIFY_SKELETON_CHARS) } : { path: file, missing: true });
+  }
+  return { reviewToken: reviewToken(kind, name, entry, evidence), skeletons, truncated: files.length > VERIFY_MAX_FILES_PER_ENTRY };
+}
+function createSnapshotEvidenceReader(access) {
+  const hashes = /* @__PURE__ */ new Map();
+  return async (kind, name, entry) => {
+    const files = "files" in entry ? entry.files : entry.chain;
+    const evidence = [];
+    for (const file of files.slice(0, VERIFY_MAX_FILES_PER_ENTRY)) {
+      let hash2 = hashes.get(file);
+      if (!hash2) {
+        hash2 = access.read(file).then((full) => full ? sourceHash(full.content) : null);
+        hashes.set(file, hash2);
+      }
+      evidence.push({ path: file, hash: await hash2 });
+    }
+    return {
+      reviewToken: reviewToken(kind, name, entry, evidence),
+      evidenceAvailable: evidence.length > 0 && evidence.every((file) => file.hash !== null)
+    };
+  };
+}
+var VERIFY_MAX_FILES_PER_ENTRY, VERIFY_SKELETON_CHARS, sourceHash;
+var init_review = __esm({
+  "src/snapshot/review.ts"() {
+    "use strict";
+    init_snapshot();
+    VERIFY_MAX_FILES_PER_ENTRY = 8;
+    VERIFY_SKELETON_CHARS = 500;
+    sourceHash = (content2) => createHash5("sha256").update(content2).digest("hex");
+  }
+});
+
+// src/snapshot/trust.ts
+function createSnapshotTrustReader(root) {
+  let reader;
+  return async (kind, name, entry, freshness) => {
+    const trust = assessTrust(entry, freshness);
+    const verdict = entry.verificationFailed ? "failed" : entry.verifiedAt ? "passed" : void 0;
+    if (!verdict) return trust;
+    trust.recordedVerdict = verdict;
+    const unknown = (reason2) => {
+      trust.verification = "unknown";
+      trust.reasons.push(reason2);
+      return trust;
+    };
+    if (!entry.verificationToken || !/^[a-f0-9]{64}$/.test(entry.verificationToken)) return unknown("The recorded verdict has no supported evidence token; obtain a fresh verify_snapshot review.");
+    try {
+      reader ??= createFileAccess(root).then(createSnapshotEvidenceReader).catch(() => null);
+      const readReview = await reader;
+      if (!readReview) return unknown("Verification source evidence could not be read under the current file policy.");
+      const review = await readReview(kind, name, entry);
+      if (!review.evidenceAvailable) {
+        return unknown("Verification source evidence is missing, excluded, unreadable, or empty; the recorded verdict cannot be confirmed.");
+      }
+      if (review.reviewToken !== entry.verificationToken) {
+        trust.verification = "stale";
+        trust.reasons.push("The entry or sampled source contents differ from the recorded verification evidence; obtain a fresh review.");
+      }
+      return trust;
+    } catch {
+      return unknown("Verification source evidence could not be read under the current file policy.");
+    }
+  };
+}
+async function readSnapshotTrustIndex(readTrust, snapshot, drift) {
+  const features = /* @__PURE__ */ Object.create(null), flows = /* @__PURE__ */ Object.create(null);
+  for (const [name, entry] of Object.entries(snapshot.features)) {
+    features[name] = await readTrust("feature", name, entry, drift?.featureFreshness?.[name] ?? "unknown");
+  }
+  for (const [name, entry] of Object.entries(snapshot.flows)) {
+    flows[name] = await readTrust("flow", name, entry, drift?.flowFreshness?.[name] ?? "unknown");
+  }
+  return { features, flows };
+}
+var init_trust2 = __esm({
+  "src/snapshot/trust.ts"() {
+    "use strict";
+    init_trust();
+    init_files();
+    init_review();
+  }
+});
+
 // src/setup/files.ts
 var files_exports = {};
 __export(files_exports, {
@@ -4893,7 +5062,7 @@ Mason provides recorded decisions and file impact over MCP. A concept map is opt
 - Before editing a file \u2192 \`get_impact\` to check references, tests, and historical change partners.
 - Investigation or correction reveals a reusable project lesson \u2192 \`save_decision\` before finishing. Capture only the lasting constraint and reason, with anchors and known sources, owner, and recorder. This creates a proposal; never infer approval. Preserve uncertain causes and unknown attribution. Route project lessons here; keep personal preferences in agent memory. Skip code summaries, current checkout status, temporary task permissions, session trivia, and secrets. No qualifying lesson means no record.
 - Before saving, compare the lesson with matching \`get_context\` records and any pending proposal. If new evidence changes the same lesson's assumptions, scope, or recommended action, revise it with \`save_decision(id: existingId)\`, including when it is accepted. Preserve supported rationale and sources, replace obsolete instructions, and add the new evidence. Create a separate record for a genuinely distinct lesson; skip unchanged restatements. Revision preserves history and leaves the accepted version operative until authorized review.
-- Consult trust metadata before relying on entries: unknown or changed freshness requires inspection, and failed verification means the description must be corrected. Check approval too: proposals are suggestions, legacy records are unreviewed, and accepted decisions are recorded constraints subject to freshness checks. An accepted revision remains operative while a pending proposal is reviewed; keep both versions and their freshness distinct.
+- Consult trust metadata before relying on entries: unknown or changed freshness requires inspection, stale or unknown map verification requires a fresh evidence review, and a recorded failed verdict means the description must be corrected. Check approval too: proposals are suggestions, legacy records are unreviewed, and accepted decisions are recorded constraints subject to freshness checks. An accepted revision remains operative while a pending proposal is reviewed; keep both versions and their freshness distinct.
 - Asked to review or re-verify a decision \u2192 \`review_decision\` first to inspect content, sources, history, and code changes. Record acceptance, reaffirmation, or retirement only when authorized by the user or a cited team review, with the actual reviewer and reason. Never infer approval from unchanged code. Review and commit the local record through the normal project workflow.
 - For an architectural overview, use \`get_snapshot\` if a map is available. If \`map.status\` is missing or invalid, use available decisions and source evidence; do not start building a map unless requested.
 - \`mason_init\` returns documentation audit and committed-diff review results, plus a short setup guide. Pass \`evidence\` with local CI manifest paths to include test and analysis results; the CLI equivalent is \`mason-review --evidence <manifest>\`. State skipped, unavailable, stale, or unknown checks explicitly. Related accepted decisions identify review context, not proven violations.
@@ -5666,7 +5835,7 @@ async function computeReview(rootDir, base, options = {}) {
   return finalize();
 }
 var exec5, MAX_ANALYZED_FILES;
-var init_review = __esm({
+var init_review2 = __esm({
   "src/review/review.ts"() {
     "use strict";
     init_drift();
@@ -5755,7 +5924,7 @@ var init_onboarding = __esm({
   "src/mcp/onboarding.ts"() {
     "use strict";
     init_audit();
-    init_review();
+    init_review2();
     init_drift();
     init_snapshot();
     init_provenance();
@@ -6171,6 +6340,7 @@ async function assembleContext(rootDir, task, files) {
     };
   }
   const drift = await computeDrift(resolvedRoot);
+  const readTrust = createSnapshotTrustReader(resolvedRoot);
   const featureScores = Object.entries(snapshot.features).map(([name, feat]) => ({
     name,
     feat,
@@ -6197,14 +6367,7 @@ async function assembleContext(rootDir, task, files) {
     Object.assign(bundle, await collectImpact(resolvedRoot, [...anchorFiles, ...Object.values(decisions).flatMap((d) => [...d.files, ...d.pendingProposal?.files ?? []])]));
     bundle.diagnostics = store.diagnostics;
     bundle.freshness = drift;
-    bundle.trust = {
-      features: Object.fromEntries(Object.entries(snapshot.features).map(
-        ([name, entry]) => [name, assessTrust(entry, drift?.featureFreshness?.[name] ?? "unknown")]
-      )),
-      flows: Object.fromEntries(Object.entries(snapshot.flows).map(
-        ([name, entry]) => [name, assessTrust(entry, drift?.flowFreshness?.[name] ?? "unknown")]
-      ))
-    };
+    bundle.trust = await readSnapshotTrustIndex(readTrust, snapshot, drift);
     bundle.hint += " " + trustHint([
       ...Object.values(bundle.trust.features),
       ...Object.values(bundle.trust.flows),
@@ -6217,7 +6380,7 @@ async function assembleContext(rootDir, task, files) {
   const features = {};
   const staleMatches = [];
   for (const { name, feat, score } of featureScores) {
-    const trust = assessTrust(feat, drift?.featureFreshness?.[name] ?? "unknown");
+    const trust = await readTrust("feature", name, feat, drift?.featureFreshness?.[name] ?? "unknown");
     const stale2 = trust.freshness !== "current";
     if (stale2) staleMatches.push(name);
     features[name] = {
@@ -6232,7 +6395,7 @@ async function assembleContext(rootDir, task, files) {
   }
   const flows = {};
   for (const { name, flow, score } of flowScores) {
-    const trust = assessTrust(flow, drift?.flowFreshness?.[name] ?? "unknown");
+    const trust = await readTrust("flow", name, flow, drift?.flowFreshness?.[name] ?? "unknown");
     const stale2 = trust.freshness !== "current";
     if (stale2) staleMatches.push(name);
     flows[name] = {
@@ -6317,6 +6480,7 @@ var init_assemble = __esm({
     "use strict";
     init_snapshot();
     init_files();
+    init_trust2();
     init_drift();
     init_impact();
     init_lexical();
@@ -6979,9 +7143,9 @@ var init_renderer = __esm({
 // src/confluence/diff.ts
 import fs24 from "fs/promises";
 import path33 from "path";
-import { createHash as createHash5 } from "crypto";
+import { createHash as createHash6 } from "crypto";
 function hashDescription(description) {
-  return createHash5("sha256").update(description, "utf8").digest("hex");
+  return createHash6("sha256").update(description, "utf8").digest("hex");
 }
 function syncStateDir(rootDir) {
   return path33.join(rootDir, ".mason");
@@ -8207,8 +8371,8 @@ async function reviewState(root, record) {
     changedFiles: touchedPaths(committed),
     localChanges: matchingPaths(anchors, workingTree.changedFiles)
   };
-  const reviewToken = createHash4("sha256").update(JSON.stringify({ record, evidence, workingTreeAvailable: workingTree.available })).digest("hex");
-  return { reviewToken, evidence, committed, workingTreeAvailable: workingTree.available };
+  const reviewToken2 = createHash4("sha256").update(JSON.stringify({ record, evidence, workingTreeAvailable: workingTree.available })).digest("hex");
+  return { reviewToken: reviewToken2, evidence, committed, workingTreeAvailable: workingTree.available };
 }
 async function previews(root, record, state) {
   const access = await createFileAccess(root);
@@ -8314,7 +8478,9 @@ async function reviewDecision(root, input) {
 // src/mcp/tools.ts
 init_drift2();
 init_snapshot();
+init_trust2();
 init_drift();
+init_review();
 
 // src/snapshot/prompt.ts
 var BATCH_SYSTEM_PROMPT = `You are Mason, building one piece of a larger concept-to-files map via a Map-Reduce pattern.
@@ -8411,6 +8577,7 @@ ${JSON.stringify({ partials }, null, 2)}`;
 }
 
 // src/snapshot/partials.ts
+init_lock();
 init_storage();
 init_snapshot();
 import fs16 from "fs/promises";
@@ -8426,7 +8593,7 @@ var partialSchema = z11.object({
 var scopeSchema2 = z11.object({ files: z11.array(z11.string()), savedAt: z11.string() });
 async function savePartial(rootDir, partial) {
   if (!/^[a-zA-Z0-9_-]+$/.test(partial.batchId)) throw new Error(`Invalid batchId: ${partial.batchId}`);
-  await writeStoreJson(rootDir, `${DIRECTORY}/${partial.batchId}.json`, partialSchema.parse(partial));
+  await withSnapshotWrite(rootDir, () => writeStoreJson(rootDir, `${DIRECTORY}/${partial.batchId}.json`, partialSchema.parse(partial)));
 }
 async function loadAllPartials(rootDir) {
   let entries;
@@ -8446,14 +8613,16 @@ async function loadAllPartials(rootDir) {
   return partials.sort((a, b) => a.offset - b.offset);
 }
 async function saveScope(rootDir, files) {
-  await writeStoreJson(rootDir, `${DIRECTORY}/scope.json`, { files, savedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  await withSnapshotWrite(rootDir, () => writeStoreJson(rootDir, `${DIRECTORY}/scope.json`, { files, savedAt: (/* @__PURE__ */ new Date()).toISOString() }));
 }
 async function loadScope(rootDir) {
   const raw = await readStoreJson(rootDir, `${DIRECTORY}/scope.json`);
   return raw === null ? null : scopeSchema2.parse(raw).files;
 }
 async function clearScope(rootDir) {
-  await fs16.rm(await storePath(rootDir, `${DIRECTORY}/scope.json`), { force: true });
+  await withSnapshotWrite(rootDir, async () => {
+    await fs16.rm(await storePath(rootDir, `${DIRECTORY}/scope.json`), { force: true });
+  });
 }
 async function clearAllPartials(rootDir) {
   await fs16.rm(await storePath(rootDir, DIRECTORY), { recursive: true, force: true });
@@ -8719,9 +8888,9 @@ async function getSnapshot(dir) {
   const store = await loadDecisionStore2(rootDir);
   const decisionRecords = store.records;
   const decisionDrift = await computeDecisionDrift(rootDir, decisionRecords);
+  const readTrust = createSnapshotTrustReader(rootDir);
   const trust = {
-    features: Object.fromEntries(Object.entries(snapshot.features).map(([name, entry]) => [name, assessTrust(entry, drift?.featureFreshness?.[name] ?? "unknown")])),
-    flows: Object.fromEntries(Object.entries(snapshot.flows).map(([name, entry]) => [name, assessTrust(entry, drift?.flowFreshness?.[name] ?? "unknown")])),
+    ...await readSnapshotTrustIndex(readTrust, snapshot, drift),
     decisions: Object.fromEntries(decisionRecords.filter((d) => d.status === "active").map((d) => [d.id, decisionTrust(effectiveDecision(d), decisionDrift.freshness?.[d.id] ?? "unknown")]))
   };
   output.trust = trust;
@@ -8981,86 +9150,82 @@ function sanitizePaths(rootDir, files) {
 }
 async function saveSnapshotData(dir, features, flows, removeFeatures = [], removeFlows = []) {
   const rootDir = path34.resolve(dir);
-  const gitHash = await getCurrentGitHash(rootDir);
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  for (const feat of Object.values(features)) {
-    feat.files = sanitizePaths(rootDir, feat.files);
-    if (feat.tests) feat.tests = sanitizePaths(rootDir, feat.tests);
-    feat.type = normalizeFeatureType(feat.type);
-  }
-  for (const flow of Object.values(flows)) {
-    flow.chain = sanitizePaths(rootDir, flow.chain);
-  }
-  const partials = await loadAllPartials(rootDir);
-  const replaceMode = partials.length > 0;
-  const previous = await loadSnapshot(rootDir);
-  const existing = replaceMode ? null : previous;
-  const preserveVerification = (next, old) => {
-    if (!old) return;
-    const semantic = (entry) => JSON.stringify({
-      description: entry.description,
-      files: "files" in entry ? entry.files : void 0,
-      chain: "chain" in entry ? entry.chain : void 0,
-      tests: "files" in entry ? entry.tests : void 0,
-      type: "files" in entry ? normalizeFeatureType(entry.type) : void 0
-    });
-    if (semantic(next) !== semantic(old)) return;
-    next.verifiedAt = old.verifiedAt;
-    next.verifiedHash = old.verifiedHash;
-    next.verificationFailed = old.verificationFailed;
-    next.verificationNote = old.verificationNote;
-  };
-  for (const [name, entry] of Object.entries(features)) preserveVerification(entry, previous?.features[name]);
-  for (const [name, entry] of Object.entries(flows)) preserveVerification(entry, previous?.flows[name]);
-  if (existing) {
-    if (existing.gitHash !== "unknown") {
-      for (const feat of Object.values(existing.features)) {
-        feat.refreshedHash ??= existing.gitHash;
+  return updateSnapshot(rootDir, async (previous) => {
+    const gitHash = await getCurrentGitHash(rootDir);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    for (const feat of Object.values(features)) {
+      feat.files = sanitizePaths(rootDir, feat.files);
+      if (feat.tests) feat.tests = sanitizePaths(rootDir, feat.tests);
+      feat.type = normalizeFeatureType(feat.type);
+    }
+    for (const flow of Object.values(flows)) {
+      flow.chain = sanitizePaths(rootDir, flow.chain);
+    }
+    const partials = await loadAllPartials(rootDir);
+    const replaceMode = partials.length > 0;
+    const existing = replaceMode ? null : previous;
+    const preserveVerification = (next, old) => {
+      delete next.verifiedAt;
+      delete next.verifiedHash;
+      delete next.verificationToken;
+      delete next.verificationFailed;
+      delete next.verificationNote;
+      if (!old) return;
+      if (JSON.stringify(snapshotEntryContent(next)) !== JSON.stringify(snapshotEntryContent(old))) return;
+      next.verificationToken = old.verificationToken;
+      next.verifiedAt = old.verifiedAt;
+      next.verifiedHash = old.verifiedHash;
+      next.verificationFailed = old.verificationFailed;
+      next.verificationNote = old.verificationNote;
+    };
+    for (const [name, entry] of Object.entries(features)) preserveVerification(entry, previous?.features[name]);
+    for (const [name, entry] of Object.entries(flows)) preserveVerification(entry, previous?.flows[name]);
+    if (existing) {
+      if (existing.gitHash !== "unknown") {
+        for (const feat of Object.values(existing.features)) {
+          feat.refreshedHash ??= existing.gitHash;
+        }
+        for (const flow of Object.values(existing.flows)) {
+          flow.refreshedHash ??= existing.gitHash;
+        }
       }
-      for (const flow of Object.values(existing.flows)) {
-        flow.refreshedHash ??= existing.gitHash;
+      const removedFeatures = removeFeatures.filter(
+        (name) => name in existing.features
+      );
+      const removedFlows = removeFlows.filter((name) => name in existing.flows);
+      for (const name of removedFeatures) delete existing.features[name];
+      for (const name of removedFlows) delete existing.flows[name];
+      if (gitHash !== "unknown") {
+        for (const feat of Object.values(features)) feat.refreshedHash = gitHash;
+        for (const flow of Object.values(flows)) flow.refreshedHash = gitHash;
       }
-    }
-    const removedFeatures = removeFeatures.filter(
-      (name) => name in existing.features
-    );
-    const removedFlows = removeFlows.filter((name) => name in existing.flows);
-    for (const name of removedFeatures) delete existing.features[name];
-    for (const name of removedFlows) delete existing.flows[name];
-    if (gitHash !== "unknown") {
-      for (const feat of Object.values(features)) feat.refreshedHash = gitHash;
-      for (const flow of Object.values(flows)) flow.refreshedHash = gitHash;
-    }
-    existing.features = { ...existing.features, ...features };
-    existing.flows = { ...existing.flows, ...flows };
-    existing.updatedAt = now;
-    existing.gitHash = gitHash;
-    await saveSnapshot(rootDir, existing);
-    await clearAllPartials(rootDir);
-    return JSON.stringify({
-      status: "updated",
-      mode: "merged",
-      features: Object.keys(existing.features).length,
-      flows: Object.keys(existing.flows).length,
-      removedFeatures: removedFeatures.length,
-      removedFlows: removedFlows.length
-    });
-  }
-  const snapshot = {
-    version: 2,
-    createdAt: now,
-    updatedAt: now,
-    gitHash,
-    features,
-    flows
-  };
-  await saveSnapshot(rootDir, snapshot);
-  await clearAllPartials(rootDir);
-  return JSON.stringify({
-    status: replaceMode ? "replaced" : "created",
-    mode: replaceMode ? "replaced-from-partials" : "fresh",
-    features: Object.keys(features).length,
-    flows: Object.keys(flows).length
+      existing.features = { ...existing.features, ...features };
+      existing.flows = { ...existing.flows, ...flows };
+      existing.updatedAt = now;
+      existing.gitHash = gitHash;
+      return { snapshot: existing, afterSave: () => clearAllPartials(rootDir), result: JSON.stringify({
+        status: "updated",
+        mode: "merged",
+        features: Object.keys(existing.features).length,
+        flows: Object.keys(existing.flows).length,
+        removedFeatures: removedFeatures.length,
+        removedFlows: removedFlows.length
+      }) };
+    }
+    const snapshot = {
+      version: 2,
+      createdAt: now,
+      updatedAt: now,
+      gitHash,
+      features,
+      flows
+    };
+    return { snapshot, afterSave: () => clearAllPartials(rootDir), result: JSON.stringify({
+      status: replaceMode ? "replaced" : "created",
+      mode: replaceMode ? "replaced-from-partials" : "fresh",
+      features: Object.keys(features).length,
+      flows: Object.keys(flows).length
+    }) };
   });
 }
 async function getImpact(dir, files) {
@@ -9070,8 +9235,6 @@ async function getImpact(dir, files) {
   return JSON.stringify(result, null, 2);
 }
 var VERIFY_DEFAULT_SAMPLE = 5;
-var VERIFY_MAX_FILES_PER_ENTRY = 8;
-var VERIFY_SKELETON_CHARS = 500;
 async function verifySnapshot(dir, sample = VERIFY_DEFAULT_SAMPLE) {
   const rootDir = path34.resolve(dir);
   const snapshot = await loadSnapshot(rootDir);
@@ -9107,25 +9270,13 @@ async function verifySnapshot(dir, sample = VERIFY_DEFAULT_SAMPLE) {
   const picked = entries.slice(0, Math.max(1, sample));
   const toVerify = [];
   for (const entry of picked) {
-    const skeletons = [];
-    for (const filePath of entry.files.slice(0, VERIFY_MAX_FILES_PER_ENTRY)) {
-      const full = await access.read(filePath);
-      if (full) {
-        skeletons.push({
-          path: full.path,
-          content: full.content.slice(0, VERIFY_SKELETON_CHARS)
-        });
-      } else {
-        skeletons.push({ path: filePath, missing: true });
-      }
-    }
+    const stored = entry.kind === "feature" ? snapshot.features[entry.name] : snapshot.flows[entry.name];
     toVerify.push({
       name: entry.name,
       kind: entry.kind,
       description: entry.description,
       lastVerified: entry.verifiedAt ?? "never",
-      skeletons,
-      truncated: entry.files.length > VERIFY_MAX_FILES_PER_ENTRY
+      ...await prepareSnapshotReview(access, entry.kind, entry.name, stored)
     });
   }
   const neverVerified = entries.filter((e) => !e.verifiedAt).length;
@@ -9134,45 +9285,81 @@ async function verifySnapshot(dir, sample = VERIFY_DEFAULT_SAMPLE) {
     totalEntries: entries.length,
     neverVerified,
     entries: toVerify,
-    instructions: 'For each entry, judge from the skeletons whether the listed files actually implement the claimed feature/flow (missing files count against it). Then call save_verification with verdicts: {"<entry name>": {"ok": true|false, "note": "<one line, required when ok is false>"}}. Be skeptical \u2014 a plausible description is not evidence; the files must show it.'
+    instructions: 'Judge whether the files implement each claimed feature/flow, then call save_verification with verdicts: {"<entry name>": {"kind": "<feature|flow from the entry>", "reviewToken": "<token from the entry>", "ok": true|false, "note": "<required when ok is false>"}}. Tokens cover the entry and full contents of the previewed files (at most 8), including unavailable-file markers; previews themselves are truncated. This is a spot-check, not proof of unshown files. A conflict requires verify_snapshot and a fresh review; never reuse a verdict for changed content. If a feature and flow share a name, submit their verdicts in separate calls.'
   });
 }
 async function saveVerification(dir, verdicts) {
   const rootDir = path34.resolve(dir);
-  const snapshot = await loadSnapshot(rootDir);
-  if (!snapshot) {
-    return JSON.stringify({ exists: false, hint: "No concept map exists." });
-  }
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const verifiedHash = await getCurrentGitHash(rootDir);
-  const stamped = [];
-  const unknown = [];
-  const failed = [];
-  for (const [name, verdict] of Object.entries(verdicts)) {
-    const entry = snapshot.features[name] ?? snapshot.flows[name];
-    if (!entry) {
-      unknown.push(name);
-      continue;
-    }
-    entry.verifiedAt = now;
-    entry.verifiedHash = verifiedHash;
-    if (verdict.ok) {
-      delete entry.verificationFailed;
-      delete entry.verificationNote;
-    } else {
-      entry.verificationFailed = true;
-      entry.verificationNote = verdict.note ?? "verification failed";
-      failed.push(name);
-    }
-    stamped.push(name);
-  }
-  snapshot.updatedAt = now;
-  await saveSnapshot(rootDir, snapshot);
-  return JSON.stringify({
-    stamped,
-    unknown,
-    failed,
-    hint: failed.length > 0 ? `Entries [${failed.join(", ")}] are mis-mapped. Re-map them: read their actual files, correct the entries, and call save_snapshot with only those entries (plus removeFeatures/removeFlows if a concept no longer exists).` : "All sampled entries verified. Re-run verify_snapshot periodically \u2014 it always picks the least-recently-verified entries next."
+  return updateSnapshot(rootDir, async (snapshot) => {
+    if (!snapshot) {
+      return { snapshot: null, result: JSON.stringify({ exists: false, stamped: [], hint: "No concept map exists. Build it and run verify_snapshot before recording verdicts." }) };
+    }
+    const stamped = [], unknown = [], failed = [];
+    const conflicts = [], reviewRequired = [], invalid = [];
+    const candidates = [];
+    let access;
+    for (const [name, verdict] of Object.entries(verdicts)) {
+      if (!verdict.kind || !["feature", "flow"].includes(verdict.kind) || !/^[a-f0-9]{64}$/.test(verdict.reviewToken ?? "")) {
+        reviewRequired.push(name);
+        continue;
+      }
+      if (typeof verdict.ok !== "boolean" || !verdict.ok && !verdict.note?.trim()) {
+        invalid.push(name);
+        continue;
+      }
+      const collection = verdict.kind === "feature" ? snapshot.features : snapshot.flows;
+      if (!Object.hasOwn(collection, name)) {
+        unknown.push(name);
+        conflicts.push(name);
+        continue;
+      }
+      const entry = collection[name];
+      access ??= await createFileAccess(rootDir);
+      const current = await prepareSnapshotReview(access, verdict.kind, name, entry);
+      if (current.reviewToken !== verdict.reviewToken) conflicts.push(name);
+      else candidates.push({ name, verdict, entry });
+    }
+    const verifiedHash = candidates.length ? await getCurrentGitHash(rootDir) : "unknown";
+    const freshAccess = candidates.length ? await createFileAccess(rootDir) : null;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    for (const { name, verdict, entry } of candidates) {
+      const current = await prepareSnapshotReview(freshAccess, verdict.kind, name, entry);
+      if (current.reviewToken !== verdict.reviewToken) {
+        conflicts.push(name);
+        continue;
+      }
+      entry.verifiedAt = now;
+      entry.verifiedHash = verifiedHash;
+      entry.verificationToken = verdict.reviewToken;
+      if (verdict.ok) {
+        delete entry.verificationFailed;
+        delete entry.verificationNote;
+      } else {
+        entry.verificationFailed = true;
+        entry.verificationNote = verdict.note.trim();
+        failed.push(name);
+      }
+      stamped.push(name);
+    }
+    const rejected = conflicts.length + reviewRequired.length + invalid.length;
+    const status = rejected ? stamped.length ? "partial" : conflicts.length ? "conflict" : reviewRequired.length ? "review_required" : "invalid" : stamped.length ? "saved" : "unchanged";
+    const hints = [];
+    if (conflicts.length) hints.push(`Entries [${conflicts.join(", ")}] changed or were deleted after review. Run verify_snapshot and review current evidence before retrying.`);
+    if (reviewRequired.length) hints.push(`Entries [${reviewRequired.join(", ")}] need kind and reviewToken from verify_snapshot. Inspect that evidence before submitting a verdict.`);
+    if (invalid.length) hints.push(`Entries [${invalid.join(", ")}] need a boolean ok and a non-empty note when ok is false.`);
+    if (failed.length) hints.push(`Entries [${failed.join(", ")}] are mis-mapped. Re-map them: read their actual files, correct the entries, and call save_snapshot with only those entries (plus removeFeatures/removeFlows if a concept no longer exists). Then run verify_snapshot for fresh review tokens.`);
+    if (!hints.length) hints.push(stamped.length ? "All submitted entries verified against the reviewed evidence. Re-run verify_snapshot periodically." : "No verdicts submitted; nothing changed.");
+    if (stamped.length) snapshot.updatedAt = now;
+    return { snapshot: stamped.length ? snapshot : null, result: JSON.stringify({
+      status,
+      stamped,
+      unknown,
+      failed,
+      conflicts,
+      reviewRequired,
+      invalid,
+      hint: hints.join(" ")
+    }) };
   });
 }
 async function saveDecision(dir, input) {
@@ -9402,10 +9589,10 @@ function createMcpServer() {
   const server = new McpServer(
     {
       name: "mason",
-      version: "0.17.4"
+      version: "0.18.0"
     },
     {
-      instructions: (setupNotice ? setupNotice + "\n\n" : "") + 'Mason retrieves recorded decisions, file impact, and optional feature/flow maps. Use get_context with the task and known files, and get_impact before editing. Save learned rationale and constraints with save_decision; review and commit the local records through the project workflow. These tools work without initialization or a concept map. Consult trust and diagnostics: changed or unknown freshness needs source inspection, failed verification needs correction, and proposals are suggestions and legacy records are unreviewed. Accepted decisions are recorded team constraints, still subject to freshness checks. Use review_decision to prepare code evidence and record only authorized acceptance, reaffirmation, or retirement. Never invent a reviewer or treat these recorded identities as authenticated approval. mason_init returns documentation audit and committed-diff review findings with a quickstart guide. Use mode: "map" only when a full architecture map is requested. A missing map is not a setup failure; use decisions and source evidence. get_snapshot provides architecture navigation when a map is available. The mason-audit and mason-review CLIs also work without setup.'
+      instructions: (setupNotice ? setupNotice + "\n\n" : "") + 'Mason retrieves recorded decisions, file impact, and optional feature/flow maps. Use get_context with the task and known files, and get_impact before editing. Save learned rationale and constraints with save_decision; review and commit the local records through the project workflow. These tools work without initialization or a concept map. Consult trust and diagnostics: changed or unknown freshness needs source inspection, stale or unknown map verification needs a fresh review, recorded failed verdicts need correction, and proposals are suggestions and legacy records are unreviewed. Accepted decisions are recorded team constraints, still subject to freshness checks. Use review_decision to prepare code evidence and record only authorized acceptance, reaffirmation, or retirement. Never invent a reviewer or treat these recorded identities as authenticated approval. mason_init returns documentation audit and committed-diff review findings with a quickstart guide. Use mode: "map" only when a full architecture map is requested. A missing map is not a setup failure; use decisions and source evidence. get_snapshot provides architecture navigation when a map is available. The mason-audit and mason-review CLIs also work without setup.'
     }
   );
   server.tool(
@@ -9527,7 +9714,7 @@ function createMcpServer() {
   );
   server.tool(
     "get_snapshot",
-    "Return the optional feature-to-file architecture map with drift and trust evidence. If no map exists, returns exists:false plus project structure, Git signals, and test pairs. Decision capture, get_context, and get_impact still work. No initialization required.",
+    "Return the optional feature-to-file architecture map with drift and trust evidence. Map verification is rechecked against sampled source contents; stale or unknown verification requires a fresh review, and recordedVerdict preserves the historical verdict. If no map exists, returns exists:false plus project structure, Git signals, and test pairs. Decision capture, get_context, and get_impact still work. No initialization required.",
     {
       dir: z24.string().describe("Absolute path to the project root directory")
     },
@@ -9540,7 +9727,7 @@ function createMcpServer() {
   );
   server.tool(
     "get_context",
-    "Assemble task context: matching decisions with rationale, approval, owner, sources, last review, and freshness, plus related tests, file impact, and any available map entries. Proposals are suggestions; legacy records are unreviewed; accepted decisions are constraints subject to freshness. No initialization or map required. Pass task and optional files. map.status and diagnostics preserve missing or invalid knowledge. Impact covers up to three unique files, expanding directory anchors.",
+    "Assemble task context: matching decisions with rationale, approval, owner, sources, last review, and freshness, plus related tests, file impact, and any available map entries. Map verification is rechecked against sampled source contents; stale or unknown verification requires a fresh review, and recordedVerdict preserves the historical verdict. Proposals are suggestions; legacy records are unreviewed; accepted decisions are constraints subject to freshness. No initialization or map required. Pass task and optional files. map.status and diagnostics preserve missing or invalid knowledge. Impact covers up to three unique files, expanding directory anchors.",
     {
       dir: z24.string().describe("Absolute path to the project root directory"),
       task: z24.string().describe("The task, bug, or change request in natural language \u2014 e.g. 'add rate limiting to the API client' or a ticket description"),
@@ -9716,7 +9903,7 @@ function createMcpServer() {
   );
   server.tool(
     "verify_snapshot",
-    "Spot-check the concept map's CORRECTNESS (drift checks freshness; this checks entries were right to begin with). Returns a sample of entries \u2014 always the never-verified and least-recently-verified first \u2014 with skeletons of their claimed files, for you to judge whether the files actually implement what the entry claims. Report verdicts back via save_verification. Run periodically, or after an automated refresh wrote entries no human reviewed.",
+    "Spot-check the concept map's CORRECTNESS (drift checks freshness; this checks entries were right to begin with). Returns a sample of entries \u2014 always the never-verified and least-recently-verified first \u2014 with skeletons of their claimed files, for you to judge whether the files actually implement what the entry claims. Report verdicts back via save_verification with each entry\u2019s kind and reviewToken. Tokens bind the entry and bounded source evidence; changed evidence requires a fresh review. Run periodically, or after an automated refresh wrote entries no human reviewed.",
     {
       dir: z24.string().describe("Absolute path to the project root directory"),
       sample: z24.number().int().optional().describe("Entries to sample (default 5)")
@@ -9728,11 +9915,13 @@ function createMcpServer() {
   );
   server.tool(
     "save_verification",
-    "Record verify_snapshot verdicts. Entries judged ok are stamped verifiedAt; failures are flagged verificationFailed with your note and surface in get_context, get_snapshot, and mason_check_drift until corrected. Verdict notes are required for failures.",
+    "Record verify_snapshot verdicts using each entry\u2019s kind and reviewToken. Missing tokens request a fresh review; changed or deleted entries return conflicts without being stamped. Entries judged ok are stamped verifiedAt; failures are flagged verificationFailed with your note and surface in get_context, get_snapshot, and mason_check_drift until corrected. Verdict notes are required for failures.",
     {
       dir: z24.string().describe("Absolute path to the project root directory"),
       verdicts: z24.record(
         z24.object({
+          kind: z24.enum(["feature", "flow"]).optional().describe("Entry kind returned by verify_snapshot; required to record a verdict"),
+          reviewToken: z24.string().optional().describe("Copy the reviewToken from verify_snapshot after inspecting its evidence; required to record a verdict"),
           ok: z24.boolean(),
           note: z24.string().optional().describe("One line on what's wrong \u2014 required when ok is false")
         })