@xenonbyte/da-vinci-workflow 0.1.16 → 0.1.17

package/docs/zh-CN/prompt-presets/tablet-app.md

@@ -28,7 +28,7 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current tablet surfaces and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有全局 Pencil 锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not pass design checkpoint if the result ignores tablet-scale composition or collapses into a stretched phone layout.
@@ -55,7 +55,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，优先执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`。只有 session wrapper 不可用时，才退回 `ensure-pen + write-pen + check-pen-sync` 这条底层链路。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
@@ -76,7 +76,7 @@ Decompose complex pages into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
 Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
 在声明 `design complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not start code changes yet.
@@ -89,7 +89,7 @@ $da-vinci use continue for this existing tablet-product redesign workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`；只有 session wrapper 不可用时，才退回 `write-pen + check-pen-sync` 这条底层链路。
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 如果 Pencil MCP 可用，且这一轮继续做了新的 Pencil 写入，就重新运行 MCP runtime gate，并把最新结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。

package/docs/zh-CN/prompt-presets/web-app.md

@@ -28,7 +28,7 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current business logic, routes, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current product surfaces and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有全局 Pencil 锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not pass design checkpoint if the result is a generic SaaS card grid or a recolor of the old interface.
@@ -56,7 +56,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，优先执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`。只有 session wrapper 不可用时，才退回 `ensure-pen + write-pen + check-pen-sync` 这条底层链路。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
@@ -77,7 +77,7 @@ Decompose complex pages into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
 Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
 在声明 `design complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not start code changes yet.
@@ -90,7 +90,7 @@ $da-vinci use continue for this existing web-product redesign workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`；只有 session wrapper 不可用时，才退回 `write-pen + check-pen-sync` 这条底层链路。
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 如果 Pencil MCP 可用，且这一轮继续做了新的 Pencil 写入，就重新运行 MCP runtime gate，并把最新结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。

package/docs/zh-CN/workflow-examples.md

@@ -127,8 +127,8 @@ Do not treat screenshot analysis as an automatic pass if it reports hierarchy, s
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
-如果这一轮开始时还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP live 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
-如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
+优先在第一次 Pencil 编辑前执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，这样会先 seed 登记好的 `.pen` 并持有全局 Pencil 锁。
+如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 live MCP 快照重新覆盖写回同一路径。
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 Keep `.da-vinci/designs/` reserved for `.pen` files only.
@@ -174,7 +174,7 @@ Use the visual-adapter preferences declared in DA-VINCI.md.
 If frontend-skill is available, use it as the primary visual adapter.
 If it is unavailable, fall back to native Da Vinci design rules and continue.
 Persist project-local Pencil files under .da-vinci/designs/.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到这里。
+如果当前还没有登记的项目内 `.pen`，先在这里 seed 一个登记好的 `.pen`，再开始第一次 Pencil 编辑，并把后续 live 编辑持续绑定到这个路径。
 如果项目里原本已有 `.pen`，继续设计后要把当前 MCP 快照覆盖写回同一路径。
 ```
 

package/lib/audit.js

@@ -1,5 +1,7 @@
 const fs = require("fs");
 const path = require("path");
+const { getStandardPenStatePath, readPenState, hashPenDocument, readPenDocument } = require("./pen-persistence");
+const { getSessionStatePath, readSessionState } = require("./pencil-session");
 
 const IMAGE_EXPORT_PATTERN = /\.(png|jpe?g|webp|pdf)$/i;
 
@@ -105,9 +107,12 @@ function resolveScopedChangeDirs(projectRoot, changesDir, options, failures, war
 }
 
 function addMissingArtifacts(projectRoot, artifactPaths, targetList) {
-  for (const artifactPath of artifactPaths) {
+  for (const artifactPath of [...new Set(artifactPaths)]) {
     if (!pathExists(artifactPath)) {
-      targetList.push(`Missing required artifact: ${relativeTo(projectRoot, artifactPath)}`);
+      const message = `Missing required artifact: ${relativeTo(projectRoot, artifactPath)}`;
+      if (!targetList.includes(message)) {
+        targetList.push(message);
+      }
     }
   }
 }
@@ -119,6 +124,7 @@ function auditProject(projectPathInput, options = {}) {
   const designsDir = path.join(daVinciDir, "designs");
   const changesDir = path.join(daVinciDir, "changes");
   const designRegistryPath = path.join(daVinciDir, "design-registry.md");
+  const pencilSessionPath = getSessionStatePath(projectRoot);
 
   const failures = [];
   const warnings = [];
@@ -228,6 +234,64 @@ function auditProject(projectPathInput, options = {}) {
       failures.push(
         `Registered design source is missing on disk: ${relativeTo(projectRoot, registeredPenPath)}`
       );
+      continue;
+    }
+
+    const statePath = getStandardPenStatePath(registeredPenPath);
+    const state = readPenState(registeredPenPath);
+    if (!state) {
+      const message = `Registered design source is missing state metadata: ${relativeTo(projectRoot, statePath)}`;
+      if (mode === "completion") {
+        failures.push(message);
+      } else {
+        warnings.push(message);
+      }
+      continue;
+    }
+
+    const persistedDocument = readPenDocument(registeredPenPath);
+    const currentHash = hashPenDocument(persistedDocument);
+    if (state.snapshotHash !== currentHash) {
+      failures.push(
+        `Registered design source hash does not match its state metadata: ${relativeTo(projectRoot, registeredPenPath)}`
+      );
+    } else {
+      notes.push(
+        `Detected persisted design-source hash for ${relativeTo(projectRoot, registeredPenPath)}.`
+      );
+    }
+  }
+
+  const sessionState = readSessionState(projectRoot);
+  if (registeredPenPaths.length > 0 || penFiles.length > 0) {
+    if (!sessionState) {
+      const message = `Missing Pencil session state: ${relativeTo(projectRoot, pencilSessionPath)}`;
+      if (mode === "completion") {
+        failures.push(message);
+      } else {
+        warnings.push(message);
+      }
+    } else {
+      if (!sessionState.penPath) {
+        failures.push("Pencil session state is missing the bound `.pen` path.");
+      }
+
+      if (mode === "completion" && sessionState.status !== "closed") {
+        failures.push("Completion audit requires the Pencil session to be ended and recorded as `closed`.");
+      }
+
+      if (sessionState.penPath && pathExists(sessionState.penPath)) {
+        const penState = readPenState(sessionState.penPath);
+        const persistedHash = penState && penState.snapshotHash ? String(penState.snapshotHash) : "";
+
+        if (sessionState.lastPersistedHash && persistedHash && sessionState.lastPersistedHash !== persistedHash) {
+          failures.push("Pencil session state hash does not match the current persisted `.pen` state hash.");
+        } else if (persistedHash) {
+          notes.push(
+            `Detected Pencil session state for ${relativeTo(projectRoot, sessionState.penPath)}.`
+          );
+        }
+      }
     }
   }
 

package/lib/cli.js

@@ -14,8 +14,21 @@ const {
 } = require("./pencil-preflight");
 const {
   writePenFromPayloadFiles,
-  snapshotPenFile
+  snapshotPenFile,
+  ensurePenFile,
+  comparePenSync
 } = require("./pen-persistence");
+const {
+  acquirePencilLock,
+  releasePencilLock,
+  getPencilLockStatus
+} = require("./pencil-lock");
+const {
+  beginPencilSession,
+  persistPencilSession,
+  endPencilSession,
+  getPencilSessionStatus
+} = require("./pencil-session");
 
 function getOption(args, name) {
   const direct = args.find((arg) => arg.startsWith(`${name}=`));
@@ -78,14 +91,24 @@ function printHelp() {
       "  da-vinci validate-assets",
       "  da-vinci audit [project-path]",
       "  da-vinci preflight-pencil --ops-file <path>",
+      "  da-vinci ensure-pen --output <path>",
       "  da-vinci write-pen --output <path> --nodes-file <path> [--variables-file <path>]",
+      "  da-vinci check-pen-sync --pen <path> --nodes-file <path> [--variables-file <path>]",
       "  da-vinci snapshot-pen --input <path> --output <path>",
+      "  da-vinci pencil-lock acquire --project <path>",
+      "  da-vinci pencil-lock release --project <path>",
+      "  da-vinci pencil-lock status",
+      "  da-vinci pencil-session begin --project <path> --pen <path>",
+      "  da-vinci pencil-session persist --project <path> --pen <path> --nodes-file <path> [--variables-file <path>]",
+      "  da-vinci pencil-session end --project <path> --pen <path> [--nodes-file <path>]",
+      "  da-vinci pencil-session status --project <path>",
       "  da-vinci --version",
       "",
       "Options:",
       "  --platform <value>   codex, claude, gemini, or all",
       "  --home <path>        override HOME for installation targets",
       "  --project <path>     override project path for audit",
+      "  --pen <path>         registered .pen path for sync checks",
       "  --ops-file <path>    Pencil batch operations file for preflight",
       "  --input <path>       input .pen file for snapshot-pen",
       "  --output <path>      output .pen file for write-pen or snapshot-pen",
@@ -94,7 +117,10 @@ function printHelp() {
       "  --verify-open        reopen the written .pen with Pencil after writing",
       "  --version <value>    explicit .pen version when writing from MCP payloads",
       "  --mode <value>       integrity or completion",
-      "  --change <id>        scope completion audit to one change id"
+      "  --change <id>        scope completion audit to one change id",
+      "  --wait-ms <value>    wait for the global Pencil lock before failing",
+      "  --owner <value>      human-readable lock owner label",
+      "  --force              force a lock release held by another project"
     ].join("\n")
   );
 }
@@ -181,6 +207,30 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "ensure-pen") {
+    const outputPath = getOption(argv, "--output");
+    const version = getOption(argv, "--version");
+    const verifyWithPencil = argv.includes("--verify-open");
+
+    if (!outputPath) {
+      throw new Error("`ensure-pen` requires `--output <path>`.");
+    }
+
+    const result = ensurePenFile({
+      outputPath,
+      version,
+      verifyWithPencil
+    });
+
+    console.log(`${result.created ? "Created" : "Verified existing"} .pen source at ${result.outputPath}`);
+    console.log(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
+    if (result.verification) {
+      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
+    }
+    return;
+  }
+
   if (command === "write-pen") {
     const outputPath = getOption(argv, "--output");
     const nodesFile = getOption(argv, "--nodes-file");
@@ -201,6 +251,8 @@ async function runCli(argv) {
     });
 
     console.log(`Wrote .pen file to ${result.outputPath}`);
+    console.log(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
     console.log(`Top-level nodes: ${result.document.children.length}`);
     if (result.verification) {
       console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
@@ -208,6 +260,44 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "check-pen-sync") {
+    const penPath = getOption(argv, "--pen");
+    const nodesFile = getOption(argv, "--nodes-file");
+    const variablesFile = getOption(argv, "--variables-file");
+    const version = getOption(argv, "--version");
+
+    if (!penPath || !nodesFile) {
+      throw new Error("`check-pen-sync` requires `--pen <path>` and `--nodes-file <path>`.");
+    }
+
+    const result = comparePenSync({
+      penPath,
+      nodesFile,
+      variablesFile,
+      version
+    });
+
+    if (!result.inSync) {
+      throw new Error(
+        [
+          "Registered `.pen` is out of sync with the provided live payload.",
+          `Pen: ${result.penPath}`,
+          `State file: ${result.statePath}`,
+          `Persisted hash: ${result.persistedHash}`,
+          `Live hash: ${result.liveHash}`
+        ].join("\n")
+      );
+    }
+
+    console.log(`Registered .pen is in sync: ${result.penPath}`);
+    console.log(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.liveHash}`);
+    if (!result.usedStateFile) {
+      console.log("State file was missing; sync comparison fell back to hashing the disk .pen file directly.");
+    }
+    return;
+  }
+
   if (command === "snapshot-pen") {
     const inputPath = getOption(argv, "--input");
     const outputPath = getOption(argv, "--output");
@@ -226,6 +316,8 @@ async function runCli(argv) {
     });
 
     console.log(`Snapshotted ${result.inputPath} to ${result.outputPath}`);
+    console.log(`State file: ${result.statePath}`);
+    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
     console.log(`Top-level nodes: ${result.document.children.length}`);
     if (result.verification) {
       console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
@@ -233,6 +325,174 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "pencil-lock") {
+    const subcommand = getPositionalArgs(argv.slice(1), [
+      "--home",
+      "--project",
+      "--owner",
+      "--wait-ms"
+    ])[0];
+    const projectPath = getOption(argv, "--project") || process.cwd();
+    const owner = getOption(argv, "--owner");
+    const waitMs = getOption(argv, "--wait-ms");
+    const force = argv.includes("--force");
+
+    if (!subcommand || ["acquire", "release", "status"].includes(subcommand) === false) {
+      throw new Error("`pencil-lock` requires one of: acquire, release, status.");
+    }
+
+    if (subcommand === "acquire") {
+      const result = acquirePencilLock({
+        projectPath,
+        owner,
+        waitMs,
+        homeDir
+      });
+      console.log(`${result.alreadyHeld ? "Reused" : "Acquired"} Pencil lock at ${result.lockPath}`);
+      console.log(`Project: ${result.lock.projectPath}`);
+      console.log(`Owner: ${result.lock.owner}`);
+      return;
+    }
+
+    if (subcommand === "release") {
+      const result = releasePencilLock({
+        projectPath,
+        force,
+        homeDir
+      });
+      if (!result.hadLock) {
+        console.log(`No Pencil lock was present at ${result.lockPath}`);
+        return;
+      }
+      console.log(`Released Pencil lock at ${result.lockPath}`);
+      console.log(`Previous project: ${result.lock.projectPath}`);
+      return;
+    }
+
+    const result = getPencilLockStatus({ homeDir });
+    console.log(`Lock path: ${result.lockPath}`);
+    if (!result.lock) {
+      console.log("Status: unlocked");
+      return;
+    }
+    console.log("Status: locked");
+    console.log(`Project: ${result.lock.projectPath}`);
+    console.log(`Owner: ${result.lock.owner}`);
+    console.log(`PID: ${result.lock.pid}`);
+    return;
+  }
+
+  if (command === "pencil-session") {
+    const subcommand = getPositionalArgs(argv.slice(1), [
+      "--home",
+      "--project",
+      "--pen",
+      "--nodes-file",
+      "--variables-file",
+      "--version",
+      "--owner",
+      "--wait-ms"
+    ])[0];
+    const projectPath = getOption(argv, "--project") || process.cwd();
+    const penPath = getOption(argv, "--pen");
+    const nodesFile = getOption(argv, "--nodes-file");
+    const variablesFile = getOption(argv, "--variables-file");
+    const version = getOption(argv, "--version");
+    const verifyWithPencil = argv.includes("--verify-open");
+    const owner = getOption(argv, "--owner");
+    const waitMs = getOption(argv, "--wait-ms");
+    const force = argv.includes("--force");
+
+    if (!subcommand || ["begin", "persist", "end", "status"].includes(subcommand) === false) {
+      throw new Error("`pencil-session` requires one of: begin, persist, end, status.");
+    }
+
+    if (subcommand === "begin") {
+      if (!penPath) {
+        throw new Error("`pencil-session begin` requires `--pen <path>`.");
+      }
+
+      const result = beginPencilSession({
+        projectPath,
+        penPath,
+        version,
+        verifyWithPencil,
+        owner,
+        waitMs,
+        homeDir
+      });
+
+      console.log(`Began Pencil session for ${result.projectRoot}`);
+      console.log(`Pen path: ${result.penPath}`);
+      console.log(`Session state: ${result.sessionStatePath}`);
+      console.log(`Snapshot hash: ${result.session.lastPersistedHash}`);
+      return;
+    }
+
+    if (subcommand === "persist") {
+      if (!penPath || !nodesFile) {
+        throw new Error("`pencil-session persist` requires `--pen <path>` and `--nodes-file <path>`.");
+      }
+
+      const result = persistPencilSession({
+        projectPath,
+        penPath,
+        nodesFile,
+        variablesFile,
+        version,
+        verifyWithPencil,
+        homeDir
+      });
+
+      console.log(`Persisted Pencil session for ${result.projectRoot}`);
+      console.log(`Pen path: ${result.penPath}`);
+      console.log(`Session state: ${result.sessionStatePath}`);
+      console.log(`Snapshot hash: ${result.session.lastPersistedHash}`);
+      console.log(`In sync: ${result.syncResult.inSync ? "yes" : "no"}`);
+      return;
+    }
+
+    if (subcommand === "end") {
+      if (!penPath) {
+        throw new Error("`pencil-session end` requires `--pen <path>`.");
+      }
+
+      const result = endPencilSession({
+        projectPath,
+        penPath,
+        nodesFile,
+        variablesFile,
+        version,
+        homeDir,
+        force
+      });
+
+      console.log(`Ended Pencil session for ${result.projectRoot}`);
+      console.log(`Pen path: ${result.penPath}`);
+      console.log(`Session state: ${result.sessionStatePath}`);
+      console.log(`Final status: ${result.session.status}`);
+      if (result.syncResult) {
+        console.log(`Final sync verified: ${result.syncResult.inSync ? "yes" : "no"}`);
+      }
+      return;
+    }
+
+    const result = getPencilSessionStatus({
+      projectPath,
+      homeDir
+    });
+
+    console.log(`Project: ${result.projectRoot}`);
+    console.log(`Session state: ${result.sessionStatePath}`);
+    console.log(`Session status: ${result.session ? result.session.status : "missing"}`);
+    console.log(`Lock status: ${result.lockStatus.lock ? "locked" : "unlocked"}`);
+    if (result.session) {
+      console.log(`Pen path: ${result.session.penPath}`);
+      console.log(`Last persisted hash: ${result.session.lastPersistedHash || "(missing)"}`);
+    }
+    return;
+  }
+
   throw new Error(`Unknown command: ${command}`);
 }
 

package/lib/mcp-runtime-gate.js

@@ -52,6 +52,10 @@ function resolveProjectPath(projectRoot, targetPath) {
   return path.normalize(path.resolve(projectRoot, targetPath));
 }
 
+function normalizeHash(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
 function isUnnamedEditor(activeEditor) {
   const normalized = normalizeEditorName(activeEditor).toLowerCase();
   return normalized === "" || normalized === "new";
@@ -91,12 +95,17 @@ function derivePhase(snapshot) {
 
 function evaluateSourceConvergence(snapshot) {
   const notes = [];
+  const phase = derivePhase(snapshot);
   const activeEditor = normalizeEditorName(snapshot.activeEditor);
   const registeredPenPath = normalizeRegisteredPath(snapshot.registeredPenPath);
   const projectRoot = typeof snapshot.projectRoot === "string" ? snapshot.projectRoot.trim() : "";
   const shellVisiblePenExists = Boolean(snapshot.shellVisiblePenExists);
   const documentedReconciliation = Boolean(snapshot.documentedReconciliation);
   const noNewPencilEditsYet = Boolean(snapshot.noNewPencilEditsYet);
+  const usedEmptyFilePath = Boolean(snapshot.usedEmptyFilePath);
+  const penSyncVerified = snapshot.penSyncVerified === true;
+  const liveSnapshotHash = normalizeHash(snapshot.liveSnapshotHash);
+  const persistedSnapshotHash = normalizeHash(snapshot.persistedSnapshotHash);
 
   if (Boolean(snapshot.mcpAvailable) === false) {
     return {
@@ -119,6 +128,13 @@ function evaluateSourceConvergence(snapshot) {
     };
   }
 
+  if (usedEmptyFilePath) {
+    return {
+      status: BLOCK,
+      notes: ["Pencil operations used an empty `filePath` even though the workflow has a registered project-local `.pen` source."]
+    };
+  }
+
   if (!shellVisiblePenExists) {
     return {
       status: BLOCK,
@@ -142,6 +158,29 @@ function evaluateSourceConvergence(snapshot) {
     };
   }
 
+  if (phase === "completion") {
+    if (!penSyncVerified) {
+      return {
+        status: BLOCK,
+        notes: ["No explicit live-to-disk `.pen` sync verification was recorded before completion."]
+      };
+    }
+
+    if (!liveSnapshotHash || !persistedSnapshotHash) {
+      return {
+        status: BLOCK,
+        notes: ["Completion requires both live and persisted `.pen` snapshot hashes."]
+      };
+    }
+
+    if (liveSnapshotHash !== persistedSnapshotHash) {
+      return {
+        status: BLOCK,
+        notes: ["Current live Pencil snapshot does not match the last persisted `.pen` snapshot."]
+      };
+    }
+  }
+
   if (noNewPencilEditsYet) {
     notes.push("No new Pencil edits were recorded yet; source convergence is only provisionally confirmed.");
     return {
@@ -150,9 +189,16 @@ function evaluateSourceConvergence(snapshot) {
     };
   }
 
+  if (penSyncVerified) {
+    notes.push("Live Pencil snapshot was explicitly verified against the persisted project-local `.pen` source.");
+  }
+
   return {
     status: PASS,
-    notes: ["Active Pencil editor matches the registered project-local `.pen` source and the file exists on disk."]
+    notes: [
+      "Active Pencil editor matches the registered project-local `.pen` source and the file exists on disk.",
+      ...notes
+    ]
   };
 }
 
@@ -296,6 +342,9 @@ function evaluateMcpRuntimeGate(snapshot = {}) {
     shellVisiblePenPath:
       typeof snapshot.shellVisiblePenPath === "string" ? snapshot.shellVisiblePenPath.trim() : "",
     shellVisiblePenExists: Boolean(snapshot.shellVisiblePenExists),
+    penSyncVerified: snapshot.penSyncVerified === true,
+    liveSnapshotHash: normalizeHash(snapshot.liveSnapshotHash),
+    persistedSnapshotHash: normalizeHash(snapshot.persistedSnapshotHash),
     claimedAnchorIds: normalizeArray(snapshot.claimedAnchorIds),
     claimedReviewedScreenIds: normalizeArray(snapshot.claimedReviewedScreenIds),
     reviewTargets: normalizeArray(snapshot.reviewTargets),
@@ -320,6 +369,9 @@ function formatMcpRuntimeGateSection(snapshot, result, options = {}) {
     `- Registered \`.pen\` path: ${result.registeredPenPath || "(missing)"}`,
     `- Shell-visible \`.pen\` path: ${result.shellVisiblePenPath || "(missing)"}`,
     `- Shell-visible \`.pen\` exists: ${result.shellVisiblePenExists ? "yes" : "no"}`,
+    `- Pen sync verified: ${result.penSyncVerified ? "yes" : "no"}`,
+    `- Live snapshot hash: ${result.liveSnapshotHash || "(missing)"}`,
+    `- Persisted snapshot hash: ${result.persistedSnapshotHash || "(missing)"}`,
     `- Claimed anchor ids: ${result.claimedAnchorIds.length > 0 ? result.claimedAnchorIds.join(", ") : "(none)"}`,
     `- Reviewed screen ids: ${result.claimedReviewedScreenIds.length > 0 ? result.claimedReviewedScreenIds.join(", ") : "(none)"}`,
     `- Screenshot target ids: ${result.reviewTargets.length > 0 ? result.reviewTargets.join(", ") : "(none)"}`,