@hanna84/mcp-writing 2.9.7 → 2.9.9

package/CHANGELOG.md

@@ -4,11 +4,31 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v2.9.9](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.9.8...v2.9.9)
+
+- refactor(db): replace ad-hoc migration checks with numbered migration… [`#102`](https://github.com/hannasdev/mcp-writing.git
+/pull/102)
+
+#### [v2.9.8](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.9.7...v2.9.8)
+
+> 26 April 2026
+
+- refactor(tools): extract registerEditingTools into tools/editing.js [`#101`](https://github.com/hannasdev/mcp-writing.git
+/pull/101)
+- Release 2.9.8 [`6e7d649`](https://github.com/hannasdev/mcp-writing.git
+/commit/6e7d64997cd22b6111a7053ef6050b568443c6b5)
+
 #### [v2.9.7](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.9.6...v2.9.7)
 
+> 26 April 2026
+
 - refactor(tools): extract registerStyleguideTools into tools/styleguide.js [`#100`](https://github.com/hannasdev/mcp-writing.git
 /pull/100)
+- Release 2.9.7 [`b2e552b`](https://github.com/hannasdev/mcp-writing.git
+/commit/b2e552b30e510c7a94e80f56758cb0c8260445bf)
 
 #### [v2.9.6](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.9.5...v2.9.6)

package/db.js

@@ -119,28 +119,31 @@ export const SCHEMA = `
   CREATE VIRTUAL TABLE IF NOT EXISTS scenes_fts USING fts5(
     scene_id, project_id, logline, title, keywords
   );
-`;
-
-export function openDb(dbPath) {
-  const db = new DatabaseSync(dbPath);
-  db.exec(SCHEMA);
 
-  const sceneColumns = db.prepare(`PRAGMA table_info(scenes)`).all();
-  if (!sceneColumns.some(column => column.name === "chapter_title")) {
-    db.exec(`ALTER TABLE scenes ADD COLUMN chapter_title TEXT;`);
-  }
+  CREATE TABLE IF NOT EXISTS schema_version (
+    id      INTEGER PRIMARY KEY CHECK (id = 1),
+    version INTEGER NOT NULL
+  );
+`;
 
-  // Rebuild legacy FTS table if it predates keyword indexing.
-  // Preserve existing indexed rows so metadata search remains available
-  // even before the next sync pass repopulates from source files.
-  const ftsSql = db.prepare(`
-    SELECT sql
-    FROM sqlite_master
-    WHERE type = 'table' AND name = 'scenes_fts'
-  `).get()?.sql;
-  if (typeof ftsSql === "string" && !ftsSql.toLowerCase().includes("keywords")) {
-    db.exec(`BEGIN IMMEDIATE;`);
-    try {
+// Each function is applied exactly once, in order, when version < its index+1.
+// Each migration runs inside a transaction with the version bump — crash-safe.
+// Migrations must be idempotent (guard against already-applied state).
+// Never edit existing entries — add new ones at the end.
+const MIGRATIONS = [
+  // 1: add chapter_title column to scenes
+  (db) => {
+    const sceneColumns = db.prepare(`PRAGMA table_info(scenes)`).all();
+    if (!sceneColumns.some(c => c.name === "chapter_title")) {
+      db.exec(`ALTER TABLE scenes ADD COLUMN chapter_title TEXT;`);
+    }
+  },
+  // 2: rebuild FTS table to include keywords column (preserve existing rows)
+  (db) => {
+    const ftsSql = db.prepare(`
+      SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'scenes_fts'
+    `).get()?.sql;
+    if (typeof ftsSql === "string" && !ftsSql.toLowerCase().includes("keywords")) {
       db.exec(`
         CREATE VIRTUAL TABLE scenes_fts_migrating USING fts5(
           scene_id, project_id, logline, title, keywords
@@ -153,12 +156,40 @@ export function openDb(dbPath) {
       `);
       db.exec(`DROP TABLE scenes_fts;`);
       db.exec(`ALTER TABLE scenes_fts_migrating RENAME TO scenes_fts;`);
+    }
+  },
+];
+
+// The version every database should reach after openDb. Not the current DB value —
+// query schema_version directly if you need the live version of a specific database.
+export const CURRENT_SCHEMA_VERSION = MIGRATIONS.length;
+
+function applyMigrations(db) {
+  db.prepare(`INSERT OR IGNORE INTO schema_version (id, version) VALUES (1, 0)`).run();
+  for (;;) {
+    db.exec(`BEGIN IMMEDIATE;`);
+    try {
+      const { version } = db.prepare(`SELECT version FROM schema_version WHERE id = 1`).get();
+      if (version >= MIGRATIONS.length) {
+        db.exec(`COMMIT;`);
+        break;
+      }
+      MIGRATIONS[version](db);
+      // WHERE version = ? ensures the bump is monotonic: a concurrent opener
+      // that advanced the version first will cause this UPDATE to match 0 rows,
+      // which is safe — the migration is already applied.
+      db.prepare(`UPDATE schema_version SET version = ? WHERE id = 1 AND version = ?`).run(version + 1, version);
       db.exec(`COMMIT;`);
     } catch (err) {
       db.exec(`ROLLBACK;`);
       throw err;
     }
   }
+}
 
+export function openDb(dbPath) {
+  const db = new DatabaseSync(dbPath);
+  db.exec(SCHEMA);
+  applyMigrations(db);
   return db;
 }

package/index.js

@@ -10,10 +10,9 @@ import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import matter from "gray-matter";
 import yaml from "js-yaml";
-import { z } from "zod";
 import { openDb } from "./db.js";
-import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, getFileWriteDiagnostics, readMeta, indexSceneFile, sidecarPath, isStructuralProjectId } from "./sync.js";
-import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit } from "./git.js";
+import { syncAll, isSyncDirWritable, getSyncOwnershipDiagnostics, sidecarPath, isStructuralProjectId } from "./sync.js";
+import { isGitAvailable, isGitRepository, initGitRepository, getSceneProseAtCommit } from "./git.js";
 import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
 import { ASYNC_PROGRESS_PREFIX } from "./async-progress.js";
 import { STYLEGUIDE_CONFIG_BASENAME } from "./prose-styleguide.js";
@@ -23,6 +22,7 @@ import { registerSearchTools } from "./tools/search.js";
 import { registerMetadataTools } from "./tools/metadata.js";
 import { registerReviewBundleTools } from "./tools/review-bundles.js";
 import { registerStyleguideTools } from "./tools/styleguide.js";
+import { registerEditingTools } from "./tools/editing.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
@@ -1022,12 +1022,15 @@ function createMcpServer() {
     createCanonicalWorldEntity,
     resolveOutputDirWithinSync,
     isPathCandidateInsideSyncDir,
+    pendingProposals,
+    generateProposalId,
   };
   registerSyncTools(s, toolContext);
   registerSearchTools(s, toolContext);
   registerMetadataTools(s, toolContext);
   registerReviewBundleTools(s, toolContext);
   registerStyleguideTools(s, toolContext);
+  registerEditingTools(s, toolContext);
 
   // ---- get_runtime_config --------------------------------------------------
   s.tool(
@@ -1052,297 +1055,6 @@ function createMcpServer() {
   );
 
   // ---- prose styleguide ---------------------------------------------------
-  // ---- PHASE 3: Prose Editing (git-backed) --------------------------------
-
-  // ---- propose_edit --------------------------------------------------------
-  s.tool(
-    "propose_edit",
-    "Generate a proposed revision for a scene. Returns a proposal_id and a diff preview. Nothing is written yet — you must call commit_edit to apply the change. This tool requires git to be available.",
-    {
-      scene_id: z.string().describe("The scene_id to revise (e.g. 'sc-011-sebastian')."),
-      instruction: z.string().describe("A brief instruction for the edit (e.g. 'Tighten the opening paragraph'). Used in the git commit message."),
-      revised_prose: z.string().describe("The complete revised prose text for the scene."),
-    },
-    async ({ scene_id, instruction, revised_prose }) => {
-      if (!GIT_ENABLED) {
-        return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported. Ensure git is installed and the sync directory is writable.");
-      }
-
-      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
-      if (!scene) {
-        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found. Hint: call find_scenes to get valid scene IDs.`);
-      }
-
-      try {
-        // Read current prose
-        const raw = fs.readFileSync(scene.file_path, "utf8");
-        const { data: metadata, content: currentProse } = matter(raw);
-
-        // Generate a simple diff representation
-        const currentLines = currentProse.trim().split("\n");
-        const revisedLines = revised_prose.trim().split("\n");
-        const diffLines = [];
-        const maxLines = Math.max(currentLines.length, revisedLines.length);
-
-        // Simple line-by-line diff
-        for (let i = 0; i < Math.min(3, maxLines); i++) {
-          const curr = currentLines[i] || "(removed)";
-          const rev = revisedLines[i] || "(removed)";
-          if (curr !== rev) {
-            diffLines.push(`- ${curr.substring(0, 80)}`);
-            diffLines.push(`+ ${rev.substring(0, 80)}`);
-          }
-        }
-        if (maxLines > 3) {
-          diffLines.push(`... (${maxLines - 3} more lines)`);
-        }
-
-        const proposalId = generateProposalId();
-        pendingProposals.set(proposalId, {
-          scene_id,
-          scene_file_path: scene.file_path,
-          instruction,
-          revised_prose,
-          original_prose: currentProse,
-          metadata,
-          created_at: new Date().toISOString(),
-        });
-
-        const summary = {
-          proposal_id: proposalId,
-          scene_id,
-          instruction,
-          diff_preview: diffLines.join("\n"),
-          note: "Review the diff above. Call commit_edit with this proposal_id to apply the change.",
-        };
-
-        return jsonResponse(summary);
-      } catch (err) {
-        if (err.code === "ENOENT") {
-          return errorResponse("STALE_PATH", `Prose file for scene '${scene_id}' not found at indexed path.`, { indexed_path: scene.file_path });
-        }
-        return errorResponse("IO_ERROR", `Failed to read scene file: ${err.message}`);
-      }
-    }
-  );
-
-  // ---- commit_edit ---------------------------------------------------------
-  s.tool(
-    "commit_edit",
-    "Apply a proposed edit and commit it to git. First creates a pre-edit snapshot, then writes the revised prose and metadata back to disk. The scene metadata stale flag is cleared.",
-    {
-      scene_id: z.string().describe("The scene_id being revised."),
-      proposal_id: z.string().describe("The proposal_id returned by propose_edit."),
-    },
-    async ({ scene_id, proposal_id }) => {
-      if (!GIT_ENABLED) {
-        return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported.");
-      }
-
-      const proposal = pendingProposals.get(proposal_id);
-      if (!proposal) {
-        return errorResponse("PROPOSAL_NOT_FOUND", `Proposal '${proposal_id}' not found or has expired. Hint: call propose_edit again to create a fresh proposal_id.`);
-      }
-
-      if (proposal.scene_id !== scene_id) {
-        return errorResponse("INVALID_EDIT", `Proposal '${proposal_id}' is for scene '${proposal.scene_id}', not '${scene_id}'.`);
-      }
-
-      try {
-        const proseWriteDiagnostics = getFileWriteDiagnostics(proposal.scene_file_path);
-        if (proseWriteDiagnostics.stat_error_code === "EACCES" || proseWriteDiagnostics.stat_error_code === "EPERM") {
-          return errorResponse(
-            "PROSE_FILE_NOT_WRITABLE",
-            "Scene prose file cannot be accessed by the current runtime user.",
-            {
-              indexed_path: proposal.scene_file_path,
-              prose_write_diagnostics: proseWriteDiagnostics,
-            }
-          );
-        }
-
-        if (proseWriteDiagnostics.stat_error_code && proseWriteDiagnostics.stat_error_code !== "ENOENT" && proseWriteDiagnostics.stat_error_code !== "ENOTDIR") {
-          return errorResponse(
-            "IO_ERROR",
-            "Failed to inspect scene prose path before writing.",
-            {
-              indexed_path: proposal.scene_file_path,
-              prose_write_diagnostics: proseWriteDiagnostics,
-            }
-          );
-        }
-
-        if (!proseWriteDiagnostics.exists) {
-          return errorResponse("STALE_PATH", "Prose file not found at indexed path.", {
-            indexed_path: proposal.scene_file_path,
-            prose_write_diagnostics: proseWriteDiagnostics,
-          });
-        }
-
-        if (!proseWriteDiagnostics.is_file) {
-          return errorResponse("INVALID_PROSE_PATH", "Indexed prose path is not a regular file.", {
-            indexed_path: proposal.scene_file_path,
-            prose_write_diagnostics: proseWriteDiagnostics,
-          });
-        }
-
-        if (!proseWriteDiagnostics.writable) {
-          return errorResponse(
-            "PROSE_FILE_NOT_WRITABLE",
-            "Scene prose file is not writable by the current runtime user.",
-            {
-              indexed_path: proposal.scene_file_path,
-              prose_write_diagnostics: proseWriteDiagnostics,
-            }
-          );
-        }
-
-        // Reconstruct file content, preserving frontmatter only if the original had it
-        const hasFrontmatter = proposal.metadata && Object.keys(proposal.metadata).length > 0;
-        const content = hasFrontmatter
-          ? `---\n${yaml.dump(proposal.metadata)}---\n\n${proposal.revised_prose}\n`
-          : `${proposal.revised_prose}\n`;
-
-        // Create pre-edit snapshot (commits current state before overwriting)
-        const snapshot = createSnapshot(SYNC_DIR, proposal.scene_file_path, scene_id, proposal.instruction);
-
-        // Write the revised prose to disk
-        fs.writeFileSync(proposal.scene_file_path, content, "utf8");
-
-        // Re-index using canonical metadata (sidecar takes precedence over inline frontmatter)
-        const { meta: canonicalMeta } = readMeta(proposal.scene_file_path, SYNC_DIR, { writable: false });
-        const { content: newProse } = matter(content);
-        indexSceneFile(db, SYNC_DIR, proposal.scene_file_path, canonicalMeta, newProse);
-
-        // Clean up the proposal
-        pendingProposals.delete(proposal_id);
-
-        const result = {
-          ok: true,
-          scene_id,
-          proposal_id,
-          snapshot_commit: snapshot.commit_hash,
-          message: `Committed edit for scene '${scene_id}'${snapshot.commit_hash ? ` (snapshot: ${snapshot.commit_hash.substring(0, 7)})` : " (no changes to snapshot)"}`,
-        };
-
-        return jsonResponse(result);
-      } catch (err) {
-        if (err.code === "ENOENT") {
-          return errorResponse("STALE_PATH", `Prose file not found at indexed path.`, { indexed_path: proposal.scene_file_path });
-        }
-        return errorResponse("IO_ERROR", `Failed to commit edit: ${err.message}`);
-      }
-    }
-  );
-
-  // ---- discard_edit --------------------------------------------------------
-  s.tool(
-    "discard_edit",
-    "Discard a pending proposal without applying it. The proposal is deleted and the prose remains unchanged.",
-    {
-      proposal_id: z.string().describe("The proposal_id to discard (from propose_edit)."),
-    },
-    async ({ proposal_id }) => {
-      const proposal = pendingProposals.get(proposal_id);
-      if (!proposal) {
-        return errorResponse("PROPOSAL_NOT_FOUND", `Proposal '${proposal_id}' not found or has already been discarded.`);
-      }
-
-      pendingProposals.delete(proposal_id);
-      return jsonResponse({
-        ok: true,
-        proposal_id,
-        message: `Discarded proposal '${proposal_id}' for scene '${proposal.scene_id}'.`,
-      });
-    }
-  );
-
-  // ---- snapshot_scene -------------------------------------------------------
-  s.tool(
-    "snapshot_scene",
-    "Manually create a git commit (snapshot) for the current state of a scene. Use this to mark important editing checkpoints outside of the propose/commit workflow.",
-    {
-      scene_id: z.string().describe("The scene_id to snapshot."),
-      project_id: z.string().describe("Project the scene belongs to."),
-      reason: z.string().describe("A brief reason for the snapshot (e.g. 'Character arc milestone reached')."),
-    },
-    async ({ scene_id, project_id, reason }) => {
-      if (!GIT_ENABLED) {
-        return errorResponse("GIT_UNAVAILABLE", "Git is not available — snapshots cannot be created.");
-      }
-
-      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ? AND project_id = ?`)
-        .get(scene_id, project_id);
-      if (!scene) {
-        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
-      }
-
-      try {
-        const snapshot = createSnapshot(SYNC_DIR, scene.file_path, scene_id, reason);
-        if (!snapshot.commit_hash) {
-          return jsonResponse({
-            ok: true,
-            scene_id,
-            reason,
-            message: "No changes to snapshot.",
-          });
-        }
-
-        return jsonResponse({
-          ok: true,
-          scene_id,
-          reason,
-          commit_hash: snapshot.commit_hash,
-          message: `Created snapshot for scene '${scene_id}': ${reason}`,
-        });
-      } catch (err) {
-        if (err.code === "ENOENT") {
-          return errorResponse("STALE_PATH", `Prose file not found at indexed path.`, { indexed_path: scene.file_path });
-        }
-        return errorResponse("IO_ERROR", `Failed to create snapshot: ${err.message}`);
-      }
-    }
-  );
-
-  // ---- list_snapshots -------------------------------------------------------
-  s.tool(
-    "list_snapshots",
-    "List git commit history for a scene, with timestamps and commit messages. Use this to find commit hashes for get_scene_prose historical retrieval.",
-    {
-      scene_id: z.string().describe("The scene_id to list snapshots for."),
-    },
-    async ({ scene_id }) => {
-      if (!GIT_ENABLED) {
-        return errorResponse("GIT_UNAVAILABLE", "Git is not available — snapshots cannot be retrieved.");
-      }
-
-      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
-      if (!scene) {
-        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found.`);
-      }
-
-      try {
-        const snapshots = listSnapshots(SYNC_DIR, scene.file_path);
-        if (!snapshots || snapshots.length === 0) {
-          return errorResponse("NO_RESULTS", `No snapshots found for scene '${scene_id}'. Try editing and committing the scene first.`);
-        }
-
-        return jsonResponse({
-          scene_id,
-          snapshots: snapshots.map(s => ({
-            commit_hash: s.commit_hash,
-            short_hash: s.commit_hash.substring(0, 7),
-            timestamp: s.timestamp,
-            message: s.message,
-          })),
-          note: "Use the commit_hash values with get_scene_prose(scene_id, commit) to retrieve a past version.",
-        });
-      } catch (err) {
-        return errorResponse("IO_ERROR", `Failed to list snapshots: ${err.message}`);
-      }
-    }
-  );
-
   return s;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.9.7",
+  "version": "2.9.9",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "type": "module",
   "main": "index.js",

package/tools/editing.js

@@ -0,0 +1,293 @@
+import { z } from "zod";
+import fs from "node:fs";
+import matter from "gray-matter";
+import yaml from "js-yaml";
+import { createSnapshot, listSnapshots } from "../git.js";
+import { getFileWriteDiagnostics, readMeta, indexSceneFile } from "../sync.js";
+
+export function registerEditingTools(s, {
+  db,
+  SYNC_DIR,
+  GIT_ENABLED,
+  errorResponse,
+  jsonResponse,
+  pendingProposals,
+  generateProposalId,
+}) {
+  // ---- propose_edit --------------------------------------------------------
+  s.tool(
+    "propose_edit",
+    "Generate a proposed revision for a scene. Returns a proposal_id and a diff preview. Nothing is written yet — you must call commit_edit to apply the change. This tool requires git to be available.",
+    {
+      scene_id: z.string().describe("The scene_id to revise (e.g. 'sc-011-sebastian')."),
+      instruction: z.string().describe("A brief instruction for the edit (e.g. 'Tighten the opening paragraph'). Used in the git commit message."),
+      revised_prose: z.string().describe("The complete revised prose text for the scene."),
+    },
+    async ({ scene_id, instruction, revised_prose }) => {
+      if (!GIT_ENABLED) {
+        return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported. Ensure git is installed and the sync directory is writable.");
+      }
+
+      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
+      if (!scene) {
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found. Hint: call find_scenes to get valid scene IDs.`);
+      }
+
+      try {
+        const raw = fs.readFileSync(scene.file_path, "utf8");
+        const { data: metadata, content: currentProse } = matter(raw);
+
+        const currentLines = currentProse.trim().split("\n");
+        const revisedLines = revised_prose.trim().split("\n");
+        const diffLines = [];
+        const maxLines = Math.max(currentLines.length, revisedLines.length);
+
+        for (let i = 0; i < Math.min(3, maxLines); i++) {
+          const curr = currentLines[i] || "(removed)";
+          const rev = revisedLines[i] || "(removed)";
+          if (curr !== rev) {
+            diffLines.push(`- ${curr.substring(0, 80)}`);
+            diffLines.push(`+ ${rev.substring(0, 80)}`);
+          }
+        }
+        if (maxLines > 3) {
+          diffLines.push(`... (${maxLines - 3} more lines)`);
+        }
+
+        const proposalId = generateProposalId();
+        pendingProposals.set(proposalId, {
+          scene_id,
+          scene_file_path: scene.file_path,
+          instruction,
+          revised_prose,
+          original_prose: currentProse,
+          metadata,
+          created_at: new Date().toISOString(),
+        });
+
+        return jsonResponse({
+          proposal_id: proposalId,
+          scene_id,
+          instruction,
+          diff_preview: diffLines.join("\n"),
+          note: "Review the diff above. Call commit_edit with this proposal_id to apply the change.",
+        });
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file for scene '${scene_id}' not found at indexed path.`, { indexed_path: scene.file_path });
+        }
+        return errorResponse("IO_ERROR", `Failed to read scene file: ${err.message}`);
+      }
+    }
+  );
+
+  // ---- commit_edit ---------------------------------------------------------
+  s.tool(
+    "commit_edit",
+    "Apply a proposed edit and commit it to git. First creates a pre-edit snapshot, then writes the revised prose and metadata back to disk. The scene metadata stale flag is cleared.",
+    {
+      scene_id: z.string().describe("The scene_id being revised."),
+      proposal_id: z.string().describe("The proposal_id returned by propose_edit."),
+    },
+    async ({ scene_id, proposal_id }) => {
+      if (!GIT_ENABLED) {
+        return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported.");
+      }
+
+      const proposal = pendingProposals.get(proposal_id);
+      if (!proposal) {
+        return errorResponse("PROPOSAL_NOT_FOUND", `Proposal '${proposal_id}' not found or has expired. Hint: call propose_edit again to create a fresh proposal_id.`);
+      }
+
+      if (proposal.scene_id !== scene_id) {
+        return errorResponse("INVALID_EDIT", `Proposal '${proposal_id}' is for scene '${proposal.scene_id}', not '${scene_id}'.`);
+      }
+
+      try {
+        const proseWriteDiagnostics = getFileWriteDiagnostics(proposal.scene_file_path);
+        if (proseWriteDiagnostics.stat_error_code === "EACCES" || proseWriteDiagnostics.stat_error_code === "EPERM") {
+          return errorResponse(
+            "PROSE_FILE_NOT_WRITABLE",
+            "Scene prose file cannot be accessed by the current runtime user.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
+        if (proseWriteDiagnostics.stat_error_code && proseWriteDiagnostics.stat_error_code !== "ENOENT" && proseWriteDiagnostics.stat_error_code !== "ENOTDIR") {
+          return errorResponse(
+            "IO_ERROR",
+            "Failed to inspect scene prose path before writing.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
+        if (!proseWriteDiagnostics.exists) {
+          return errorResponse("STALE_PATH", "Prose file not found at indexed path.", {
+            indexed_path: proposal.scene_file_path,
+            prose_write_diagnostics: proseWriteDiagnostics,
+          });
+        }
+
+        if (!proseWriteDiagnostics.is_file) {
+          return errorResponse("INVALID_PROSE_PATH", "Indexed prose path is not a regular file.", {
+            indexed_path: proposal.scene_file_path,
+            prose_write_diagnostics: proseWriteDiagnostics,
+          });
+        }
+
+        if (!proseWriteDiagnostics.writable) {
+          return errorResponse(
+            "PROSE_FILE_NOT_WRITABLE",
+            "Scene prose file is not writable by the current runtime user.",
+            {
+              indexed_path: proposal.scene_file_path,
+              prose_write_diagnostics: proseWriteDiagnostics,
+            }
+          );
+        }
+
+        const hasFrontmatter = proposal.metadata && Object.keys(proposal.metadata).length > 0;
+        const content = hasFrontmatter
+          ? `---\n${yaml.dump(proposal.metadata)}---\n\n${proposal.revised_prose}\n`
+          : `${proposal.revised_prose}\n`;
+
+        const snapshot = createSnapshot(SYNC_DIR, proposal.scene_file_path, scene_id, proposal.instruction);
+
+        fs.writeFileSync(proposal.scene_file_path, content, "utf8");
+
+        const { meta: canonicalMeta } = readMeta(proposal.scene_file_path, SYNC_DIR, { writable: false });
+        const { content: newProse } = matter(content);
+        indexSceneFile(db, SYNC_DIR, proposal.scene_file_path, canonicalMeta, newProse);
+
+        pendingProposals.delete(proposal_id);
+
+        return jsonResponse({
+          ok: true,
+          scene_id,
+          proposal_id,
+          snapshot_commit: snapshot.commit_hash,
+          message: `Committed edit for scene '${scene_id}'${snapshot.commit_hash ? ` (snapshot: ${snapshot.commit_hash.substring(0, 7)})` : " (no changes to snapshot)"}`,
+        });
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file not found at indexed path.`, { indexed_path: proposal.scene_file_path });
+        }
+        return errorResponse("IO_ERROR", `Failed to commit edit: ${err.message}`);
+      }
+    }
+  );
+
+  // ---- discard_edit --------------------------------------------------------
+  s.tool(
+    "discard_edit",
+    "Discard a pending proposal without applying it. The proposal is deleted and the prose remains unchanged.",
+    {
+      proposal_id: z.string().describe("The proposal_id to discard (from propose_edit)."),
+    },
+    async ({ proposal_id }) => {
+      const proposal = pendingProposals.get(proposal_id);
+      if (!proposal) {
+        return errorResponse("PROPOSAL_NOT_FOUND", `Proposal '${proposal_id}' not found or has already been discarded.`);
+      }
+
+      pendingProposals.delete(proposal_id);
+      return jsonResponse({
+        ok: true,
+        proposal_id,
+        message: `Discarded proposal '${proposal_id}' for scene '${proposal.scene_id}'.`,
+      });
+    }
+  );
+
+  // ---- snapshot_scene -------------------------------------------------------
+  s.tool(
+    "snapshot_scene",
+    "Manually create a git commit (snapshot) for the current state of a scene. Use this to mark important editing checkpoints outside of the propose/commit workflow.",
+    {
+      scene_id: z.string().describe("The scene_id to snapshot."),
+      project_id: z.string().describe("Project the scene belongs to."),
+      reason: z.string().describe("A brief reason for the snapshot (e.g. 'Character arc milestone reached')."),
+    },
+    async ({ scene_id, project_id, reason }) => {
+      if (!GIT_ENABLED) {
+        return errorResponse("GIT_UNAVAILABLE", "Git is not available — snapshots cannot be created.");
+      }
+
+      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ? AND project_id = ?`)
+        .get(scene_id, project_id);
+      if (!scene) {
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
+      }
+
+      try {
+        const snapshot = createSnapshot(SYNC_DIR, scene.file_path, scene_id, reason);
+        if (!snapshot.commit_hash) {
+          return jsonResponse({
+            ok: true,
+            scene_id,
+            reason,
+            message: "No changes to snapshot.",
+          });
+        }
+
+        return jsonResponse({
+          ok: true,
+          scene_id,
+          reason,
+          commit_hash: snapshot.commit_hash,
+          message: `Created snapshot for scene '${scene_id}': ${reason}`,
+        });
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file not found at indexed path.`, { indexed_path: scene.file_path });
+        }
+        return errorResponse("IO_ERROR", `Failed to create snapshot: ${err.message}`);
+      }
+    }
+  );
+
+  // ---- list_snapshots -------------------------------------------------------
+  s.tool(
+    "list_snapshots",
+    "List git commit history for a scene, with timestamps and commit messages. Use this to find commit hashes for get_scene_prose historical retrieval.",
+    {
+      scene_id: z.string().describe("The scene_id to list snapshots for."),
+    },
+    async ({ scene_id }) => {
+      if (!GIT_ENABLED) {
+        return errorResponse("GIT_UNAVAILABLE", "Git is not available — snapshots cannot be retrieved.");
+      }
+
+      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
+      if (!scene) {
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found.`);
+      }
+
+      try {
+        const snapshots = listSnapshots(SYNC_DIR, scene.file_path);
+        if (!snapshots || snapshots.length === 0) {
+          return errorResponse("NO_RESULTS", `No snapshots found for scene '${scene_id}'. Try editing and committing the scene first.`);
+        }
+
+        return jsonResponse({
+          scene_id,
+          snapshots: snapshots.map(s => ({
+            commit_hash: s.commit_hash,
+            short_hash: s.commit_hash.substring(0, 7),
+            timestamp: s.timestamp,
+            message: s.message,
+          })),
+          note: "Use the commit_hash values with get_scene_prose(scene_id, commit) to retrieve a past version.",
+        });
+      } catch (err) {
+        return errorResponse("IO_ERROR", `Failed to list snapshots: ${err.message}`);
+      }
+    }
+  );
+}