friday-mcp-v2 3.0.0 → 3.0.2

package/dist/mcp-server.js

@@ -11,6 +11,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { FridayWPClient, ConnectionRegistry } from "./wordpress-api.js";
 import { BridgeClient } from "./bridge-client.js";
 import fetch from "node-fetch";
+import { randomUUID } from "node:crypto";
 import { readFileSync, statSync, realpathSync } from "node:fs";
 import { execFile } from "node:child_process";
 import { resolve as resolvePath, sep, dirname } from "node:path";
@@ -102,6 +103,207 @@ const statusCache = {
     }
 };
 
+// ========================================
+// Snapshot キャッシュ（Phase 1: インデックスズレ対処）
+// ========================================
+
+/**
+ * djb2 ハッシュ → base36 文字列
+ * @param {string} str
+ * @returns {string}
+ */
+function simpleHash(str) {
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) + hash) + str.charCodeAt(i);
+        hash = hash & hash;
+    }
+    return (hash >>> 0).toString(36);
+}
+
+function generateSnapshotId() {
+    return 'snap_' + randomUUID().replace(/-/g, '').slice(0, 12);
+}
+
+function generateBlockRef(index) {
+    return 'r' + index;
+}
+
+/**
+ * ブロックの fingerprint を生成
+ * @param {object} block - state.allBlocks の要素
+ * @param {string} mode - "editor" | "headless"
+ * @returns {string}
+ */
+function computeFingerprint(block, mode) {
+    const type = block.type || 'unknown';
+    let contentSource;
+    if (mode === 'headless' && block.html) {
+        contentSource = block.html.slice(0, 200);
+    } else if (block.attributes) {
+        contentSource = JSON.stringify(block.attributes).slice(0, 200);
+    } else {
+        contentSource = '';
+    }
+    return type + ':' + simpleHash(contentSource);
+}
+
+/**
+ * revision を計算（内容ベースハッシュ）
+ * serialize_blocks 相当の粒度で内容変更を検知する
+ * @param {{ allBlocks: Array }} state
+ * @param {string} mode
+ * @returns {string}
+ */
+function computeRevision(state, mode) {
+    const source = state.allBlocks.map(b => {
+        const content = (mode === 'headless' && b.html)
+            ? b.html.slice(0, 200)
+            : JSON.stringify(b.attributes || {}).slice(0, 200);
+        return `${b.type}:${b.index}:${content}`;
+    }).join('|');
+    return 'rev_' + simpleHash(source);
+}
+
+/**
+ * 既に取得済みの currentState から snapshot を組み立て、キャッシュに登録して返す。
+ * buildResponseSnapshot() の「state を受け取る版」— getCurrentStructure() を呼ばない。
+ */
+function buildSnapshotFromState(currentState, mode, postId, sessionId, siteName) {
+    if (!currentState?.allBlocks || currentState.allBlocks.length === 0) return null;
+
+    const newSnapshotId = generateSnapshotId();
+    const newSnapshotBlocks = buildSnapshotBlocks(currentState, mode);
+    const newRevision = computeRevision(currentState, mode);
+
+    const snapshotRecord = {
+        snapshotId: newSnapshotId, postId, mode,
+        sessionId: mode === 'editor' ? sessionId : null,
+        siteName: siteName || 'default',
+        createdAt: Date.now(),
+        revision: newRevision,
+        blocks: newSnapshotBlocks,
+        displayMode: 'full',
+    };
+    snapshotCache.set(snapshotRecord);
+
+    return {
+        snapshotId: newSnapshotId,
+        revision: newRevision,
+        blocks: newSnapshotBlocks.map(b => ({
+            ref: b.ref, index: b.index, type: b.type,
+            depth: b.depth, parentIndex: b.parentIndex,
+        })),
+    };
+}
+
+/**
+ * expectedRevision と現在の revision を比較する。
+ * 一致すれば null を返す。不一致の場合は最新 snapshot 付きのエラーレスポンスを返す。
+ * currentState から直接 snapshot を組み立てるため、追加の通信コストなし。
+ * @returns {object|null} null=一致（続行可）、object=不一致エラーレスポンス
+ */
+function checkRevisionMismatch(expectedRevision, currentState, mode, postId, sessionId, siteName) {
+    const currentRevision = computeRevision(currentState, mode);
+    if (expectedRevision === currentRevision) return null;
+
+    // 不一致 — snapshot をキャッシュに登録（AI が新 snapshotId で refetch 可能に）
+    // Phase 2: blocks 一覧は出力しない（コンテキスト軽量化）
+    const latestSnapshot = buildSnapshotFromState(currentState, mode, postId, sessionId, siteName);
+    const snapshotLine = latestSnapshot
+        ? `\n[snapshot:${latestSnapshot.snapshotId} rev:${latestSnapshot.revision}]`
+        : '';
+    const text = `❌ REVISION_MISMATCH: expected ${expectedRevision}, actual ${currentRevision}` +
+                 snapshotLine +
+                 `\n→ get_article_structure で最新を取得してください`;
+    return { content: [{ type: "text", text }], isError: true };
+}
+
+/**
+ * state.allBlocks から SnapshotBlock[] を構築
+ * @param {{ allBlocks: Array }} state
+ * @param {string} mode
+ * @returns {Array}
+ */
+function buildSnapshotBlocks(state, mode) {
+    return state.allBlocks.map(b => ({
+        ref: generateBlockRef(b.index),
+        index: b.index,
+        type: b.type,
+        depth: b.depth || 0,
+        parentIndex: b.parentIndex ?? null,
+        fingerprint: computeFingerprint(b, mode),
+        section: b.section || null,
+    }));
+}
+
+const snapshotCache = {
+    /** @type {Map<string, object>} snapshotId → SnapshotRecord */
+    _entries: new Map(),
+    /** @type {Map<string, string[]>} "postId:siteName" → snapshotId[] (FIFO) */
+    _byArticle: new Map(),
+    TTL: 300_000,
+    MAX_PER_ARTICLE: 3,
+
+    /**
+     * snapshotId で取得（TTL チェック付き）
+     * @param {string} snapshotId
+     * @returns {object|null}
+     */
+    get(snapshotId) {
+        const entry = this._entries.get(snapshotId);
+        if (!entry) return null;
+        if ((Date.now() - entry.createdAt) >= this.TTL) {
+            this._remove(snapshotId);
+            return null;
+        }
+        return entry;
+    },
+
+    /**
+     * snapshot を登録（記事単位 eviction 付き）
+     * @param {object} record - SnapshotRecord
+     */
+    set(record) {
+        const articleKey = `${record.postId}:${record.siteName}`;
+        let articleSnaps = this._byArticle.get(articleKey) || [];
+        articleSnaps.push(record.snapshotId);
+        while (articleSnaps.length > this.MAX_PER_ARTICLE) {
+            const oldest = articleSnaps.shift();
+            this._entries.delete(oldest);
+        }
+        this._byArticle.set(articleKey, articleSnaps);
+        this._entries.set(record.snapshotId, record);
+    },
+
+    /** @param {string} snapshotId */
+    _remove(snapshotId) {
+        const entry = this._entries.get(snapshotId);
+        if (entry) {
+            const articleKey = `${entry.postId}:${entry.siteName}`;
+            const articleSnaps = this._byArticle.get(articleKey);
+            if (articleSnaps) {
+                const idx = articleSnaps.indexOf(snapshotId);
+                if (idx >= 0) articleSnaps.splice(idx, 1);
+                if (articleSnaps.length === 0) this._byArticle.delete(articleKey);
+            }
+        }
+        this._entries.delete(snapshotId);
+    },
+
+    /** @param {string} [siteName] 指定時はそのサイトのみ。省略時は全破棄。 */
+    clear(siteName) {
+        if (siteName) {
+            for (const [id, record] of this._entries) {
+                if (record.siteName === siteName) this._remove(id);
+            }
+        } else {
+            this._entries.clear();
+            this._byArticle.clear();
+        }
+    }
+};
+
 // ヘルパー関数: 正規表現用に文字列をエスケープ
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -536,8 +738,17 @@ const targetSchema = {
             required: ["level", "contains"],
             description: "Select from heading to next same-level heading.",
         },
+        ref: {
+            type: "string",
+            description: "Block ref from snapshot (e.g. 'r5'). Requires snapshotId.",
+        },
+        refs: {
+            type: "array",
+            items: { type: "string" },
+            description: "Multiple block refs from snapshot. Requires snapshotId.",
+        },
     },
-    description: "Target: one of selected/index/indices/range/heading + optional filters.",
+    description: "Target: one of selected/index/indices/range/heading/ref/refs + optional filters.",
 };
 
 const targetSchemaNoSelected = {
@@ -574,12 +785,16 @@ function normalizeTarget(target) {
         target.indices && 'indices',
         target.range && 'range',
         target.heading && 'heading',
+        target.ref && 'ref',
+        target.refs && 'refs',
     ].filter(Boolean);
     if (primaries.length > 1) {
         throw new Error(`target に複数の primary selector が指定されています: ${primaries.join(', ')}。1つだけ指定してください。`);
     }
 
     const result = {};
+    if (target.ref) result._ref = target.ref;
+    if (target.refs) result._refs = target.refs;
     if (target.selected) result.target = "selected";
     if (target.index !== undefined) result.index = target.index;
     if (target.indices) result.indices = target.indices;
@@ -628,6 +843,1051 @@ function normalizeInsert(insert) {
     return { insertOnly: true, insertPosition: pos };
 }
 
+// ========================================
+// ref 解決ヘルパー（Phase 2a）
+// ========================================
+
+/**
+ * 現在のブロック構造を取得する（ref 解決・レスポンス snapshot 用）
+ * @param {string} mode - "editor" | "headless"
+ * @param {object} client - WordPressAPI インスタンス
+ * @param {number} postId
+ * @param {string|null} sessionId
+ * @returns {Promise<object>} { allBlocks: Block[] }
+ */
+async function getCurrentStructure(mode, client, postId, sessionId, { safetyCritical = false } = {}) {
+    if (mode === 'editor') {
+        // Phase 3.1: editor からライブ状態を即時取得（session store キャッシュをバイパス）
+        try {
+            const result = await client.sendEditorCommand(
+                'get_fresh_state', {}, 10000, postId, sessionId
+            );
+            if (result?.success && result.allBlocks) {
+                return result;
+            }
+        } catch (_e) {
+            // get_fresh_state 失敗
+        }
+        // safety-critical 経路: stale キャッシュにフォールバックしない
+        if (safetyCritical) {
+            throw new Error('editor のライブ状態を取得できませんでした。拡張機能の接続を確認してください。');
+        }
+        // 非 safety-critical: 従来キャッシュにフォールバック
+        return await client.getEditorState(postId, sessionId);
+    } else {
+        const structure = await client.headlessGetStructure(postId);
+        const blocksData = await client.headlessGetBlocks(postId);
+        structure.allBlocks = blocksData.blocks;
+        return structure;
+    }
+}
+
+/**
+ * snapshot の ref を現在構造上の index に解決する
+ * @param {string} snapshotId
+ * @param {string} ref
+ * @param {string} mode - 現在の mode
+ * @param {string|null} sessionId - 現在の sessionId
+ * @param {number} postId
+ * @param {object} currentState - getCurrentStructure() の結果（キャッシュ用）
+ * @returns {number} 解決された現在の index
+ * @throws {Error} 解決不能な場合
+ */
+function resolveRefFromState(snapshotId, ref, mode, sessionId, postId, currentState) {
+    // 1. snapshot 取得
+    const snap = snapshotCache.get(snapshotId);
+    if (!snap) {
+        throw new Error(`snapshot "${snapshotId}" が見つかりません（期限切れまたは無効）。get_article_structure を再取得してください。`);
+    }
+
+    // 2. 状態ソース束縛チェック
+    if (snap.mode !== mode) {
+        throw new Error(`snapshot は ${snap.mode} モードで取得されましたが、現在は ${mode} モードです。get_article_structure を再取得してください。`);
+    }
+    if (mode === 'editor' && snap.sessionId && sessionId && snap.sessionId !== sessionId) {
+        throw new Error(`snapshot は sessionId "${snap.sessionId}" で取得されましたが、現在の sessionId は "${sessionId}" です。get_article_structure を再取得してください。`);
+    }
+    if (snap.postId !== postId) {
+        throw new Error(`snapshot は postId ${snap.postId} 用ですが、postId ${postId} に対して使用されています。`);
+    }
+
+    // 3. snapshot 内の ref 情報を取得
+    const snapBlock = snap.blocks.find(b => b.ref === ref);
+    if (!snapBlock) {
+        throw new Error(`ref "${ref}" は snapshot "${snapshotId}" 内に存在しません。`);
+    }
+
+    // 4. 現在構造の検証
+    const currentBlocks = currentState?.allBlocks;
+    if (!currentBlocks || currentBlocks.length === 0) {
+        throw new Error('現在のブロック構造を取得できませんでした。');
+    }
+
+    // 5. fingerprint 照合（2段、曖昧ならエラー）
+    const candidates = [];
+    for (const cb of currentBlocks) {
+        const fp = computeFingerprint(cb, mode);
+        if (fp === snapBlock.fingerprint) {
+            candidates.push(cb);
+        }
+    }
+
+    // 5a. 完全一致 1件 → 確定
+    if (candidates.length === 1) return candidates[0].index;
+
+    // 5b. 完全一致 複数件 → depth + parentIndex で絞り込み
+    if (candidates.length > 1) {
+        const refined = candidates.filter(c =>
+            (c.depth || 0) === snapBlock.depth &&
+            (c.parentIndex ?? null) === snapBlock.parentIndex
+        );
+        if (refined.length === 1) return refined[0].index;
+        throw new Error(
+            `ref "${ref}" (type: ${snapBlock.type}) の解決先が ${refined.length > 0 ? refined.length : candidates.length} 件見つかりました。` +
+            `一意に特定できません。get_article_structure を再取得してください。`
+        );
+    }
+
+    // 5c. 一致 0件 → エラー
+    throw new Error(
+        `ref "${ref}" (${snapBlock.type}, fingerprint: ${snapBlock.fingerprint}) に一致するブロックが見つかりません。` +
+        `構造が大幅に変更された可能性があります。get_article_structure を再取得してください。`
+    );
+}
+
+/**
+ * safety-critical な fresh state 取得 + expectedRevision チェック。
+ * state 取得と revision 判定の入口を統一し、分岐ごとのズレを防ぐ。
+ * @returns {{ currentState, error? }}
+ */
+async function acquireFreshState({
+    expectedRevision, mode, client, postId, sessionId, siteName,
+}) {
+    let currentState;
+    try {
+        currentState = await getCurrentStructure(mode, client, postId, sessionId, { safetyCritical: true });
+    } catch (e) {
+        return { error: {
+            content: [{ type: "text", text: `❌ 構造取得に失敗しました: ${e.message}${expectedRevision ? '\nexpectedRevision が指定されているため、更新を中止します。' : ''}` }],
+            isError: true,
+        }};
+    }
+    if (expectedRevision) {
+        const mismatch = checkRevisionMismatch(expectedRevision, currentState, mode, postId, sessionId, siteName);
+        if (mismatch) return { error: mismatch };
+    }
+    return { currentState };
+}
+
+/**
+ * ref/refs → index/indices 解決 + expectedRevision チェックの共通処理。
+ * delete_block / duplicate_block / update_blocks / table_operations で共通利用する。
+ * @returns {{ index?, indices?, error? }}
+ *   - 成功: { index } or { indices } or {}（ref なしで revision OK の場合）
+ *   - 失敗: { error: MCP エラーレスポンス }（呼び出し元は return error で即返却）
+ */
+async function resolveRefsAndCheckRevision({
+    snapshotId, ref, refs, expectedRevision,
+    mode, client, postId, sessionId, siteName,
+}) {
+    const hasRef = ref || refs;
+
+    // Case 1: ref/refs 指定あり
+    if (hasRef) {
+        if (!snapshotId) {
+            return { error: {
+                content: [{ type: "text", text: "❌ ref/refs を使用するには snapshotId が必要です。get_article_structure で取得してください。" }],
+                isError: true,
+            }};
+        }
+        const { currentState, error } = await acquireFreshState({
+            expectedRevision, mode, client, postId, sessionId, siteName,
+        });
+        if (error) return { error };
+        try {
+            if (ref) {
+                const index = resolveRefFromState(snapshotId, ref, mode, sessionId, postId, currentState);
+                return { index, currentState };
+            }
+            if (refs) {
+                const indices = refs.map(r => resolveRefFromState(snapshotId, r, mode, sessionId, postId, currentState));
+                return { indices, currentState };
+            }
+        } catch (e) {
+            return { error: {
+                content: [{ type: "text", text: `❌ ref 解決エラー: ${e.message}` }],
+                isError: true,
+            }};
+        }
+    }
+
+    // Case 2: ref なし + expectedRevision のみ
+    if (expectedRevision) {
+        const { currentState, error } = await acquireFreshState({
+            expectedRevision, mode, client, postId, sessionId, siteName,
+        });
+        if (error) return { error };
+        return { currentState };
+    }
+
+    // Case 3: どちらもなし
+    return {};
+}
+
+/**
+ * 下流レスポンスの blocks を buildSnapshotBlocks / computeRevision が
+ * 期待する state.allBlocks 形式に正規化する。
+ * @param {Array} blocks - 下流 formatBlocksForSnapshot() の結果
+ * @returns {{ allBlocks: Array }}
+ */
+function normalizeDownstreamBlocks(blocks) {
+    return {
+        allBlocks: blocks.map(b => ({
+            index: b.index,
+            type: b.type,
+            html: b.html || '',
+            attributes: b.attributes || {},
+            section: b.section || null,
+            depth: b.depth || 0,
+            parentIndex: b.parentIndex ?? null,
+        })),
+    };
+}
+
+/**
+ * 下流レスポンスの result.blocks から snapshot を構築する。
+ * blocks がない場合は null を返す（呼び出し元でフォールバック判断）。
+ * @param {object} result - 下流レスポンス
+ * @param {string} mode
+ * @param {number} postId
+ * @param {string|null} sessionId
+ * @param {string} siteName
+ * @returns {object|null} { snapshotId, revision, blocks[] } or null
+ */
+function buildResponseSnapshotFromResult(result, mode, postId, sessionId, siteName) {
+    const blocks = result?.blocks;
+    if (!blocks || !Array.isArray(blocks) || blocks.length === 0) {
+        return null;
+    }
+    const state = normalizeDownstreamBlocks(blocks);
+    return buildSnapshotFromState(state, mode, postId, sessionId, siteName);
+}
+
+/**
+ * 更新後のレスポンス snapshot を構築する。
+ * result が渡され、result.blocks があればそこから構築（再取得不要）。
+ * なければ従来通り getCurrentStructure() で再取得する。
+ * @param {string} mode
+ * @param {object} client
+ * @param {number} postId
+ * @param {string|null} sessionId
+ * @param {string} siteName
+ * @param {object} [result] - 下流レスポンス（Phase 1: blocks 再利用）
+ * @returns {Promise<object|null>} { snapshotId, revision, blocks[] } or null
+ */
+async function buildResponseSnapshot(mode, client, postId, sessionId, siteName, result) {
+    // Phase 1: 下流 result.blocks があればそこから構築（再取得不要）
+    if (result) {
+        const fromResult = buildResponseSnapshotFromResult(result, mode, postId, sessionId, siteName);
+        if (fromResult) return fromResult;
+    }
+    let newState;
+    try {
+        newState = await getCurrentStructure(mode, client, postId, sessionId);
+    } catch {
+        return null;
+    }
+
+    if (!newState?.allBlocks || newState.allBlocks.length === 0) {
+        return null;
+    }
+
+    const newSnapshotId = generateSnapshotId();
+    const newSnapshotBlocks = buildSnapshotBlocks(newState, mode);
+    const newRevision = computeRevision(newState, mode);
+
+    const snapshotRecord = {
+        snapshotId: newSnapshotId,
+        postId,
+        mode,
+        sessionId: mode === 'editor' ? sessionId : null,
+        siteName: siteName || 'default',
+        createdAt: Date.now(),
+        revision: newRevision,
+        blocks: newSnapshotBlocks,
+        displayMode: 'full',
+    };
+    snapshotCache.set(snapshotRecord);
+
+    return {
+        snapshotId: newSnapshotId,
+        revision: newRevision,
+        blocks: newSnapshotBlocks.map(b => ({
+            ref: b.ref,
+            index: b.index,
+            type: b.type,
+            depth: b.depth,
+            parentIndex: b.parentIndex,
+        })),
+    };
+}
+
+/**
+ * @deprecated Phase 7 で削除予定。batch 経路および index 経路の後方互換用。
+ * snapshot 情報をテキストレスポンスに付加する
+ * blocks[] を含めて AI が新しい ref を取得できるようにする
+ * @param {string} text - 元のレスポンステキスト
+ * @param {object|null} snapshot - buildResponseSnapshot の結果
+ * @param {object} [refInfo] - 単体操作の ref 解決情報（1→N 展開追跡用）
+ * @param {string} [refInfo.oldSnapshotId] - 元の snapshotId
+ * @param {string} [refInfo.usedRef] - 使用した ref
+ * @param {number} [refInfo.resolvedIndex] - 解決された元の index
+ * @returns {string} snapshot 行と blocks 一覧が付加されたテキスト
+ */
+function appendSnapshotToTextLegacy(text, snapshot, refInfo) {
+    if (!snapshot) return text;
+
+    // 1→N 展開チェック（単体操作時のみ）
+    let expandedLine = '';
+    if (refInfo?.oldSnapshotId && refInfo?.usedRef) {
+        const oldSnap = snapshotCache.get(refInfo.oldSnapshotId);
+        if (oldSnap) {
+            const oldCount = oldSnap.blocks.length;
+            const newCount = snapshot.blocks.length;
+            const delta = newCount - oldCount;
+            if (delta > 0) {
+                // 単体操作での展開: 元 index 位置から delta+1 個が新ブロック
+                const newRefs = snapshot.blocks
+                    .filter(b => b.index >= refInfo.resolvedIndex && b.index < refInfo.resolvedIndex + 1 + delta)
+                    .map(b => b.ref);
+                expandedLine = `\nexpanded: ${refInfo.usedRef} → [${newRefs.join(', ')}]`;
+            }
+        }
+    }
+
+    let out = text + `\n\n[snapshot:${snapshot.snapshotId} rev:${snapshot.revision}]${expandedLine}`;
+    if (snapshot.blocks && snapshot.blocks.length > 0) {
+        out += '\nblocks:';
+        for (const b of snapshot.blocks) {
+            const parent = b.parentIndex !== null ? `,p:${b.parentIndex}` : '';
+            out += `\n  [${b.index}|${b.ref}] ${b.type} (d:${b.depth}${parent})`;
+        }
+    }
+    return out;
+}
+
+/**
+ * Phase 5: update_blocks / insert_block の差分/Legacy 自動分岐。
+ * inputRef が null なら即 Legacy。差分構築失敗時も Legacy フォールバック。
+ * @param {string} text - メッセージ本文
+ * @param {object|null} snap - buildResponseSnapshot の結果
+ * @param {object} result - 下流レスポンス
+ * @param {object|null} preState - _preState
+ * @param {string|null} inputRef - 入力 ref（null = Legacy 固定）
+ * @param {boolean} isInsert - insertOnly 操作か
+ * @param {object|null} refInfo - Legacy フォールバック用 _refInfo
+ * @returns {string}
+ */
+function buildUpdateDiffResponse(text, snap, result, preState, inputRef, isInsert, refInfo) {
+    if (!inputRef || !snap) {
+        return appendSnapshotToTextLegacy(text, snap, refInfo);
+    }
+
+    if (isInsert) {
+        const changeInfo = buildChangeInfoFromResult('inserted', snap, result, preState);
+        if (changeInfo) return appendRefChangesToText(text, changeInfo);
+        return appendSnapshotToTextLegacy(text, snap, refInfo);
+    }
+
+    // update / expand 判定
+    // success:false の change を除外（invalid regex, parse failure 等）
+    const changes = result?.changes?.filter(c => c.success !== false);
+    if (!changes || changes.length === 0) {
+        return appendSnapshotToTextLegacy(text, snap, refInfo);
+    }
+    // filtered 済み changes で result を差し替え（buildChangeInfoFromResult が result.changes を直接参照するため）
+    const filteredResult = { ...result, changes };
+    if (changes.length === 1 && changes[0]?.newIndices?.length > 1) {
+        // 1→N 展開（単体 target のみ）
+        const changeInfo = buildChangeInfoFromResult('expanded', snap, filteredResult, preState, { inputRef });
+        if (changeInfo) return appendRefChangesToText(text, changeInfo);
+    } else if (changes.length === 1) {
+        // 1→1 更新（単体 ref で成功 1 件のときだけ差分化）
+        const changeInfo = buildChangeInfoFromResult('updated', snap, filteredResult, preState);
+        if (changeInfo) return appendRefChangesToText(text, changeInfo);
+    }
+
+    return appendSnapshotToTextLegacy(text, snap, refInfo);
+}
+
+// ============================================================
+// Phase 2: ref 変化分類ロジック（差分通知方式の基盤）
+// ============================================================
+
+/**
+ * @typedef {Object} DeletedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'deleted'} type
+ * @property {string[]} deletedRefs - 削除された ref 配列 ['r5', 'r8']
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} InsertedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'inserted'} type
+ * @property {Array<{index: number, ref: string, blockType: string, depth: number}>} inserted
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} MovedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'moved'} type
+ * @property {Array<{oldRef: string, newRef: string}>} moved
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} UpdatedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'updated'} type
+ * @property {string[]} updatedRefs - fingerprint 変化した ref 配列
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} ExpandedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'expanded'} type
+ * @property {{oldRef: string, newRefs: string[]}} expanded
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {Object} DuplicatedChange
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'duplicated'} type
+ * @property {string} sourceRef
+ * @property {string} newRef
+ * @property {number} sourceIndex
+ * @property {number} newIndex
+ * @property {boolean} [refetchRequired]
+ */
+
+/**
+ * @typedef {DeletedChange|InsertedChange|MovedChange|UpdatedChange|ExpandedChange|DuplicatedChange} ChangeInfo
+ */
+
+/**
+ * ref 変化情報をテキストに付加する��差分モード）��
+ * blocks 一��は出力しない。
+ * @param {string} text
+ * @param {ChangeInfo|null} changeInfo
+ * @returns {string}
+ */
+function appendRefChangesToText(text, changeInfo) {
+    if (!changeInfo) return text;
+
+    let out = text + `\n\n[snapshot:${changeInfo.snapshotId} rev:${changeInfo.revision}]`;
+
+    switch (changeInfo.type) {
+        case 'deleted':
+            out += `\ndeleted: [${changeInfo.deletedRefs.join(', ')}] (invalid in new snapshot)`;
+            break;
+        case 'inserted':
+            out += '\ninserted: ' + changeInfo.inserted
+                .map(b => `[${b.index}|${b.ref}] ${b.blockType} (d:${b.depth})`)
+                .join(', ');
+            break;
+        case 'moved':
+            out += '\nmoved: ' + changeInfo.moved
+                .map(m => `${m.oldRef}\u2192${m.newRef}`)
+                .join(', ');
+            break;
+        case 'updated':
+            out += `\nupdated: [${changeInfo.updatedRefs.join(', ')}] (use new snapshot)`;
+            break;
+        case 'expanded':
+            out += `\nexpanded: ${changeInfo.expanded.oldRef} \u2192 [${changeInfo.expanded.newRefs.join(', ')}]`;
+            break;
+        case 'duplicated':
+            out += `\nduplicated: ${changeInfo.sourceRef} \u2192 ${changeInfo.newRef} (source:[${changeInfo.sourceIndex}], new:[${changeInfo.newIndex}]) (use new snapshot)`;
+            break;
+    }
+
+    if (changeInfo.refetchRequired) {
+        out += '\n\u26a0 refetchRequired: \u5b50\u30d6\u30ed\u30c3\u30af\u5909\u66f4\u3042\u308a\u3002get_article_structure \u3067\u6700\u65b0\u3092\u53d6\u5f97\u3057\u3066\u304f\u3060\u3055\u3044\u3002';
+    }
+
+    return out;
+}
+
+/**
+ * @typedef {Object} BatchDiffEntry
+ * @property {number} opIndex
+ * @property {'updated'|'expanded'|'failed'|'skipped'} type
+ * @property {string} [ref] - updated/failed/skipped 時
+ * @property {string} [oldRef] - expanded 時
+ * @property {string[]} [newRefs] - expanded 時
+ * @property {string} [error] - failed 時
+ * @property {boolean} [refetchRequired] - この entry 単体の refetch 判定
+ */
+
+/**
+ * @typedef {Object} BatchDiffInfo
+ * @property {string} snapshotId
+ * @property {string} revision
+ * @property {'batch'} type
+ * @property {BatchDiffEntry[]} entries
+ * @property {boolean} [refetchRequired] - batch 全体の OR
+ */
+
+/**
+ * BatchDiffInfo をテキストに付加する（batch 差分モード）。
+ * @param {string} text
+ * @param {BatchDiffInfo|null} batchInfo
+ * @returns {string}
+ */
+function appendBatchRefChangesToText(text, batchInfo) {
+    if (!batchInfo) return text;
+
+    let out = text + `\n\n[snapshot:${batchInfo.snapshotId} rev:${batchInfo.revision}]`;
+    out += '\nchanges:';
+
+    for (const entry of batchInfo.entries) {
+        switch (entry.type) {
+            case 'updated':
+                out += `\n  [${entry.opIndex}] updated: [${entry.ref}]`;
+                break;
+            case 'expanded':
+                out += `\n  [${entry.opIndex}] expanded: ${entry.oldRef} \u2192 [${entry.newRefs.join(', ')}]`;
+                break;
+            case 'failed':
+                out += `\n  [${entry.opIndex}] failed: ${entry.ref}`;
+                if (entry.error) out += ` \u2014 ${entry.error}`;
+                break;
+            case 'skipped':
+                out += `\n  [${entry.opIndex}] skipped: ${entry.ref}`;
+                break;
+        }
+        if (entry.refetchRequired) out += ' (refetch)';
+    }
+
+    if (batchInfo.refetchRequired) {
+        out += '\n\u26a0 refetchRequired: \u5b50\u30d6\u30ed\u30c3\u30af\u5909\u66f4\u3042\u308a\u3002get_article_structure \u3067\u6700\u65b0\u3092\u53d6\u5f97\u3057\u3066\u304f\u3060\u3055\u3044\u3002';
+    }
+
+    return out;
+}
+
+// ============================================================
+// Phase 7: batch 差分化 helper
+// ============================================================
+
+/**
+ * allBlocks の parentIndex チェーンを辿り、resolvedOps 間に祖先/子孫関係があるか検出。
+ * @param {Array<{resolvedIndex: number, ref: string}>} resolvedOps
+ * @param {Array<{index: number, parentIndex: number|null}>} allBlocks
+ * @returns {{childRef: string, childIndex: number, ancestorRef: string, ancestorIndex: number}|null}
+ */
+function checkAncestorOverlap(resolvedOps, allBlocks) {
+    const targetMap = new Map(resolvedOps.map(o => [o.resolvedIndex, o.ref]));
+    const parentMap = new Map(allBlocks.map(b => [b.index, b.parentIndex ?? null]));
+
+    for (const op of resolvedOps) {
+        let current = parentMap.get(op.resolvedIndex);
+        while (current != null) {
+            if (targetMap.has(current)) {
+                return {
+                    childRef: op.ref,
+                    childIndex: op.resolvedIndex,
+                    ancestorRef: targetMap.get(current),
+                    ancestorIndex: current,
+                };
+            }
+            current = parentMap.get(current) ?? null;
+        }
+    }
+    return null;
+}
+
+/**
+ * allBlocks 内の rootIndex を含む subtree の flat size を返す。
+ * @param {Array<{index: number, parentIndex: number|null}>} allBlocks
+ * @param {number} rootIndex
+ * @returns {number}
+ */
+function countFlatSubtreeSize(allBlocks, rootIndex) {
+    const childrenOf = new Map();
+    for (const b of allBlocks) {
+        if (b.parentIndex != null) {
+            if (!childrenOf.has(b.parentIndex)) childrenOf.set(b.parentIndex, []);
+            childrenOf.get(b.parentIndex).push(b.index);
+        }
+    }
+    let count = 1;
+    const stack = childrenOf.get(rootIndex) ? [...childrenOf.get(rootIndex)] : [];
+    while (stack.length > 0) {
+        const idx = stack.pop();
+        count++;
+        const children = childrenOf.get(idx);
+        if (children) stack.push(...children);
+    }
+    return count;
+}
+
+/**
+ * opResult.blocks から新 subtree の flat size を計算する。
+ * rawNewIndices のうち集合内に親を持たないものを root とみなし、各 root の subtree size を合算。
+ * editor（top-level のみ）/ headless（flat 全体）両対応。
+ * @param {Array<{index: number, parentIndex?: number|null}>} opResultBlocks
+ * @param {number[]} rawNewIndices
+ * @returns {number}
+ */
+function computeNewFlatSize(opResultBlocks, rawNewIndices) {
+    if (!rawNewIndices || rawNewIndices.length === 0) return 0;
+    const indexSet = new Set(rawNewIndices);
+    const newRoots = rawNewIndices.filter(idx => {
+        const b = opResultBlocks.find(bl => bl.index === idx);
+        return !b || b.parentIndex == null || !indexSet.has(b.parentIndex);
+    });
+    let total = 0;
+    const blocksForSize = opResultBlocks.map(b => ({ index: b.index, parentIndex: b.parentIndex ?? null }));
+    for (const root of newRoots) {
+        total += countFlatSubtreeSize(blocksForSize, root);
+    }
+    return total;
+}
+
+/**
+ * [pre-state 戦略] 操作前の状態で対象ブロックにネスト子があるか判定。
+ * delete, move, duplicate 用。操作後は対象が消える/移動するため pre-state で見る。
+ * 下流 hasChildren フラグがあればそちらを優先（duplicate, move が返す）。
+ * @param {object|null} preState - 操作前の state
+ * @param {number[]} targetIndices - 操作対象 index 配列
+ * @param {object} [downstream] - 下流 result（hasChildren があれば優先）
+ * @returns {boolean}
+ */
+function checkRefetchFromPreState(preState, targetIndices, downstream) {
+    if (downstream?.hasChildren === true) return true;
+    if (downstream?.hasChildren === false) return false;
+
+    if (!preState?.allBlocks) return true;
+
+    for (const idx of targetIndices) {
+        const hasChild = preState.allBlocks.some(b => b.parentIndex === idx);
+        if (hasChild) return true;
+    }
+    return false;
+}
+
+/**
+ * [post-result 戦略] 操作結果にネストブロックが含ま���るか判定。
+ * insert, update 用��非ネストだったブロックを nested HTML に更新したケースを検知。
+ * 新 snapshot の blocks から、対象 index を parentIndex に持つブロックがあるかで判定。
+ * @param {object} snapshot - buildResponseSnapshot() の結果（新 snapshot）
+ * @param {number[]} resultIndices - 操作結果の index 配列（挿入/更新された位置）
+ * @returns {boolean}
+ */
+function checkRefetchFromResult(snapshot, resultIndices) {
+    if (!snapshot?.blocks || resultIndices.length === 0) return false;
+
+    for (const idx of resultIndices) {
+        const hasNested = snapshot.blocks.some(b => b.parentIndex === idx);
+        if (hasNested) return true;
+    }
+    return false;
+}
+
+/**
+ * 下流 result + 新 snapshot → ChangeInfo を構築する。
+ * 構築不能な場合は null を返す（呼び出し側は Legacy フォールバック必須）。
+ * @param {'deleted'|'inserted'|'moved'|'updated'|'expanded'|'duplicated'} type
+ * @param {object} snapshot - buildResponseSnapshot() の結果
+ * @param {object} result - 下流レスポンス
+ * @param {object|null} preState - _preState
+ * @param {object} [opts] - 追加オプション
+ * @returns {ChangeInfo|null} null = Legacy フォールバック
+ */
+function buildChangeInfoFromResult(type, snapshot, result, preState, opts) {
+    if (!snapshot?.snapshotId || !result) return null;
+
+    const base = { snapshotId: snapshot.snapshotId, revision: snapshot.revision };
+
+    switch (type) {
+        case 'deleted': {
+            const deleted = result.deleted;
+            if (!deleted || deleted.length === 0) return null;
+            const deletedRefs = opts?.inputRefs || deleted.map(d => generateBlockRef(d.index));
+            const refetch = checkRefetchFromPreState(preState, deleted.map(d => d.index), result);
+            return { ...base, type: 'deleted', deletedRefs, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'inserted': {
+            let indices = result.insertedIndices;
+            if (!indices && result.changes) {
+                indices = result.changes.flatMap(c => c.newIndices || []).filter(i => i != null);
+            }
+            if (!indices || indices.length === 0) return null;
+            // refetchRequired は全 indices で判定（子孫含む）
+            const refetch = checkRefetchFromResult(snapshot, indices);
+            // top-level のみ: 他の inserted index を parentIndex に持つものを除外
+            // （headless は subtree 全体の flat index を返すが、editor は top-level のみ。差分レスポンスは top-level に統一）
+            const indexSet = new Set(indices);
+            const topLevelIndices = indices.filter(idx => {
+                const b = snapshot.blocks?.find(bl => bl.index === idx);
+                return !b || b.parentIndex == null || !indexSet.has(b.parentIndex);
+            });
+            const inserted = topLevelIndices.map(idx => {
+                const b = snapshot.blocks?.find(bl => bl.index === idx);
+                return b
+                    ? { index: b.index, ref: b.ref, blockType: b.type, depth: b.depth }
+                    : { index: idx, ref: generateBlockRef(idx), blockType: 'unknown', depth: 0 };
+            });
+            if (inserted.length === 0) return null;
+            return { ...base, type: 'inserted', inserted, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'moved': {
+            const mapping = result.movedMapping;
+            if (!mapping || mapping.length === 0) return null;
+            // inputRefs 長さ不一致 → Legacy フォールバック（count > 1 安全弁）
+            if (opts?.inputRefs && opts.inputRefs.length !== mapping.length) return null;
+            const moved = mapping.map((m, i) => ({
+                oldRef: opts?.inputRefs ? opts.inputRefs[i] : generateBlockRef(m.oldIndex),
+                newRef: generateBlockRef(m.newIndex),
+            }));
+            const refetch = checkRefetchFromPreState(preState, mapping.map(m => m.oldIndex), result);
+            return { ...base, type: 'moved', moved, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'updated': {
+            const changes = result.changes;
+            if (!changes || changes.length === 0) return null;
+            const updatedRefs = changes.map(c => generateBlockRef(c.newIndices?.[0] ?? c.oldIndex));
+            const resultIndices = changes.flatMap(c => c.newIndices || []).filter(i => i != null);
+            const refetch = checkRefetchFromResult(snapshot, resultIndices);
+            return { ...base, type: 'updated', updatedRefs, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'expanded': {
+            const changes = result.changes || [];
+            if (changes.length !== 1) return null;
+            const change = changes[0];
+            if (!change || !change.newIndices || change.newIndices.length <= 1) return null;
+            const oldRef = opts?.inputRef || generateBlockRef(change.oldIndex);
+            const newRefs = change.newIndices.map(idx => generateBlockRef(idx));
+            const refetch = checkRefetchFromResult(snapshot, change.newIndices);
+            return { ...base, type: 'expanded', expanded: { oldRef, newRefs }, ...(refetch ? { refetchRequired: true } : {}) };
+        }
+        case 'duplicated': {
+            const srcIdx = result.sourceIndex ?? result.duplicated?.index;
+            const newIdx = result.newIndex ?? result.duplicated?.newIndex;
+            if (srcIdx == null || newIdx == null) return null;
+            const refetch = checkRefetchFromPreState(preState, [srcIdx], result);
+            return {
+                ...base, type: 'duplicated',
+                sourceRef: opts?.inputRef || generateBlockRef(srcIdx),
+                newRef: generateBlockRef(newIdx),
+                sourceIndex: srcIdx, newIndex: newIdx,
+                ...(refetch ? { refetchRequired: true } : {}),
+            };
+        }
+        default:
+            return null;
+    }
+}
+
+/**
+ * 実行完了した resolvedOps + snapshot から BatchDiffInfo を構築する。
+ * @param {Array} resolvedOps - rebasing 済みの op 配列
+ * @param {object|null} snapshot - 最終 snapshot
+ * @returns {BatchDiffInfo|null}
+ */
+function buildBatchDiffInfo(resolvedOps, snapshot) {
+    if (!snapshot?.snapshotId) return null;
+
+    let refetchRequired = false;
+    const entries = [];
+
+    // opIndex 順（入力順）でソート
+    const opsByInput = [...resolvedOps].sort((a, b) => a.opIndex - b.opIndex);
+
+    for (const op of opsByInput) {
+        if (op.status === 'failed') {
+            entries.push({ opIndex: op.opIndex, type: 'failed', ref: op.ref, error: op.error || null });
+            continue;
+        }
+        if (op.status === 'skipped') {
+            entries.push({ opIndex: op.opIndex, type: 'skipped', ref: op.ref });
+            continue;
+        }
+
+        // rebased な新 ref を snapshot から取得
+        const newRefs = (op.rebasedNewIndices || []).map(idx => {
+            const b = snapshot.blocks?.find(bl => bl.index === idx);
+            return b ? b.ref : generateBlockRef(idx);
+        });
+
+        // refetch 判定
+        const opRefetch = checkRefetchFromResult(snapshot, op.rebasedNewIndices || []);
+        if (opRefetch) refetchRequired = true;
+
+        if (op.status === 'expanded') {
+            entries.push({
+                opIndex: op.opIndex, type: 'expanded',
+                oldRef: op.ref, newRefs,
+                ...(opRefetch ? { refetchRequired: true } : {}),
+            });
+        } else {
+            // updated
+            entries.push({
+                opIndex: op.opIndex, type: 'updated',
+                ref: newRefs[0] || op.ref,
+                ...(opRefetch ? { refetchRequired: true } : {}),
+            });
+        }
+    }
+
+    return {
+        snapshotId: snapshot.snapshotId,
+        revision: snapshot.revision,
+        type: 'batch',
+        entries,
+        ...(refetchRequired ? { refetchRequired: true } : {}),
+    };
+}
+
+/**
+ * batch operations の実行
+ * @param {Array} operations - 各 operation: { target, newHTML?, replacements?, attributeUpdates? }
+ * @param {string} snapshotId
+ * @param {string} mode
+ * @param {object} client
+ * @param {number} postId
+ * @param {string|null} sessionId
+ * @param {string} siteName
+ * @param {string} _modeTag
+ * @param {string} toolName
+ */
+async function handleBatchOperations(operations, snapshotId, mode, client, postId, sessionId, siteName, _modeTag, toolName, expectedRevision) {
+    // 1. 全 operation の target を正規化 & ref を一括解決
+    let currentState;
+    try {
+        currentState = await getCurrentStructure(mode, client, postId, sessionId, { safetyCritical: true });
+    } catch (e) {
+        return { content: [{ type: "text", text: `❌ 現在のブロック構造を取得できませんでした: ${e.message}` }], isError: true };
+    }
+
+    // revision 楽観的ロック（expectedRevision が指定されている場合のみ）
+    if (expectedRevision) {
+        const mismatch = checkRevisionMismatch(
+            expectedRevision, currentState, mode, postId, sessionId, siteName
+        );
+        if (mismatch) return mismatch;
+    }
+
+    // batch は ref のみ許可（1 operation = 1 ref = 1 block）
+    const resolvedOps = [];
+    try {
+        for (let i = 0; i < operations.length; i++) {
+            const op = operations[i];
+            const ref = op.target?.ref;
+            if (!ref || typeof ref !== 'string') {
+                return {
+                    content: [{ type: "text", text: `❌ operations[${i}]: batch の target には ref（文字列）が必須です。index/section/range 等は batch では使用できません。` }],
+                    isError: true,
+                };
+            }
+            // ref 以外の selector が指定されていないか確認
+            const extraKeys = Object.keys(op.target).filter(k => k !== 'ref');
+            if (extraKeys.length > 0) {
+                return {
+                    content: [{ type: "text", text: `❌ operations[${i}]: batch の target は ref のみ指定可能です。不正なキー: ${extraKeys.join(', ')}` }],
+                    isError: true,
+                };
+            }
+
+            // 変更種別がちょうど1つか検証（1 op = 1 ref = 1 change-kind）
+            const changeKinds = [
+                op.replacements && op.replacements.length > 0 && 'replacements',
+                op.newHTML && 'newHTML',
+                op.attributeUpdates && 'attributeUpdates',
+            ].filter(Boolean);
+            if (changeKinds.length === 0) {
+                return {
+                    content: [{ type: "text", text: `❌ operations[${i}]: 変更内容が指定されていません。replacements, newHTML, attributeUpdates のいずれか1つを指定してください。` }],
+                    isError: true,
+                };
+            }
+            if (changeKinds.length > 1) {
+                return {
+                    content: [{ type: "text", text: `❌ operations[${i}]: 複数の変更種別が指定されています: ${changeKinds.join(', ')}。1つだけ指定してください。` }],
+                    isError: true,
+                };
+            }
+
+            const resolvedIndex = resolveRefFromState(snapshotId, ref, mode, sessionId, postId, currentState);
+
+            resolvedOps.push({
+                opIndex: i,
+                ref,
+                resolvedIndex,
+                newHTML: op.newHTML,
+                replacements: op.replacements,
+                attributeUpdates: op.attributeUpdates,
+            });
+        }
+    } catch (e) {
+        return { content: [{ type: "text", text: `❌ batch ref 解決エラー: ${e.message}` }], isError: true };
+    }
+
+    // 同一 index への複数 operation を排他チェック
+    const indexSet = new Set();
+    for (const op of resolvedOps) {
+        if (indexSet.has(op.resolvedIndex)) {
+            return {
+                content: [{ type: "text", text: `❌ index ${op.resolvedIndex} (ref: ${op.ref}) に対して複数の operation が指定されています。同一ブロックへの複数操作は許可されていません。` }],
+                isError: true,
+            };
+        }
+        indexSet.add(op.resolvedIndex);
+    }
+
+    // ancestor/descendant overlap チェック（親子関係の target は batch 不可）
+    const ancestorOverlap = checkAncestorOverlap(resolvedOps, currentState.allBlocks);
+    if (ancestorOverlap) {
+        return {
+            content: [{ type: "text", text: `❌ operations に親子関係の target が含まれるため batch 不可です。ref ${ancestorOverlap.childRef} (index ${ancestorOverlap.childIndex}) は ref ${ancestorOverlap.ancestorRef} (index ${ancestorOverlap.ancestorIndex}) の子孫です。` }],
+            isError: true,
+        };
+    }
+
+    // 2. oldFlatSize を計算（rebasing 用、降順ソート前に実行）
+    for (const op of resolvedOps) {
+        op.oldFlatSize = countFlatSubtreeSize(currentState.allBlocks, op.resolvedIndex);
+    }
+
+    // 3. 降順ソート（index が大きい方から処理 — 1 op = 1 index なので安全）
+    resolvedOps.sort((a, b) => b.resolvedIndex - a.resolvedIndex);
+
+    // 4. 各 operation を順次実行（結果情報を保持）
+    let lastSuccessfulResult = null;
+    for (const op of resolvedOps) {
+        const index = op.resolvedIndex;
+
+        let opResult;
+        try {
+            const downstreamParams = {
+                index,
+                replacements: op.replacements,
+                newHTML: op.newHTML,
+                attributeUpdates: op.attributeUpdates,
+                insertOnly: false,
+                dryRun: false,
+                _fromInsertBlock: false,
+            };
+            if (mode === 'headless') {
+                opResult = await client.headlessUpdate(postId, downstreamParams);
+            } else {
+                opResult = await client.sendEditorCommand("update_blocks", downstreamParams, 10000, postId, sessionId);
+            }
+        } catch (e) {
+            op.status = 'failed';
+            op.error = e.message;
+            op.rawNewIndices = [];
+            op.newFlatSize = op.oldFlatSize;
+            op.opResult = null;
+            continue;
+        }
+
+        // op 成功判定
+        const topLevelFail = !opResult || opResult.success === false || opResult.ok === false;
+        if (topLevelFail) {
+            op.status = 'failed';
+            op.error = opResult?.error || 'unknown error';
+            op.rawNewIndices = [];
+            op.newFlatSize = op.oldFlatSize;
+            op.opResult = opResult;
+            continue;
+        }
+
+        // skipped 判定（attributeUpdates の filter mismatch）
+        const successfulChanges = (opResult.changes || []).filter(c => c.success !== false);
+        const hasSkippedResult = opResult.results?.some(r => r.skipped === true);
+        if (successfulChanges.length === 0 && !topLevelFail && !opResult.error) {
+            if (hasSkippedResult || op.attributeUpdates != null) {
+                op.status = 'skipped';
+                op.rawNewIndices = [];
+                op.newFlatSize = op.oldFlatSize;
+                op.opResult = opResult;
+                continue;
+            }
+            // changes 空で skipped でもない → failed
+            op.status = 'failed';
+            op.error = 'no successful changes';
+            op.rawNewIndices = [];
+            op.newFlatSize = op.oldFlatSize;
+            op.opResult = opResult;
+            continue;
+        }
+
+        // 成功: rawNewIndices を取得
+        op.rawNewIndices = successfulChanges.flatMap(c => c.newIndices || []);
+        op.newFlatSize = (opResult.blocks && opResult.blocks.length > 0)
+            ? computeNewFlatSize(opResult.blocks, op.rawNewIndices)
+            : op.rawNewIndices.length || op.oldFlatSize;
+        op.status = (op.rawNewIndices.length > 1) ? 'expanded' : 'updated';
+        op.opResult = opResult;
+        lastSuccessfulResult = opResult;
+    }
+
+    // 5. rebasing（resolvedIndex 昇順で走査、低 index の展開が高 index をずらす）
+    const opsForRebase = [...resolvedOps].sort((a, b) => a.resolvedIndex - b.resolvedIndex);
+    let cumulativeDelta = 0;
+    for (const op of opsForRebase) {
+        if (op.status === 'failed' || op.status === 'skipped') {
+            op.rebasedNewIndices = [];
+            continue;
+        }
+        op.rebasedNewIndices = op.rawNewIndices.map(idx => idx + cumulativeDelta);
+        cumulativeDelta += (op.newFlatSize - op.oldFlatSize);
+    }
+
+    // 6. 最終 snapshot 構築
+    let snapshot;
+    if (lastSuccessfulResult) {
+        snapshot = buildResponseSnapshotFromResult(lastSuccessfulResult, mode, postId, sessionId, siteName);
+    }
+    if (!snapshot) {
+        // 全 op 失敗/skipped or result.blocks なし → currentState から構築
+        snapshot = buildSnapshotFromState(currentState, mode, postId, sessionId, siteName);
+    }
+    if (!snapshot) {
+        // 最終手段: 再取得
+        snapshot = await buildResponseSnapshot(mode, client, postId, sessionId, siteName);
+    }
+
+    // 7. BatchDiffInfo 構築
+    const batchDiff = buildBatchDiffInfo(resolvedOps, snapshot);
+
+    // 8. レスポンス組み立て
+    const successCount = resolvedOps.filter(r => r.status !== 'failed' && r.status !== 'skipped').length;
+    const totalCount = resolvedOps.length;
+    let text = `\u2705 batch \u5b8c\u4e86 (${successCount}/${totalCount} \u6210\u529f)`;
+
+    if (batchDiff) {
+        text = appendBatchRefChangesToText(text + _modeTag, batchDiff);
+    } else {
+        text = appendSnapshotToTextLegacy(text + _modeTag, snapshot);
+    }
+
+    return { content: [{ type: "text", text }] };
+}
+
 // フィードバック送信ヘルパー
 const FEEDBACK_URL = process.env.FRIDAY_FEEDBACK_URL || '';
 async function sendFeedback(data) {
@@ -776,7 +2036,7 @@ const tools = [
     },
     {
         name: "delete_block",
-        description: "Delete block(s) by index or selection.",
+        description: "Delete block(s) by index, ref, or selection.",
         inputSchema: {
             type: "object",
             properties: {
@@ -785,12 +2045,16 @@ const tools = [
                 index: { type: "number", description: "Index (0-based). Omit for selected." },
                 count: { type: "number", description: "Consecutive count (default: 1)" },
                 indices: { type: "array", items: { type: "number" }, description: "Multiple indices (exclusive with index/count)" },
+                snapshotId: { type: "string", description: "Snapshot ID from get_article_structure. Required when using ref/refs." },
+                ref: { type: "string", description: "Block ref from snapshot (exclusive with index/indices)." },
+                refs: { type: "array", items: { type: "string" }, description: "Multiple block refs (exclusive with index/indices)." },
+                expectedRevision: { type: "string", description: "Revision from snapshot. Rejects if structure changed." },
             },
         },
     },
     {
         name: "move_block",
-        description: "Move block(s). Use from/to (top-level) or fromFlat/toFlat (nested).",
+        description: "Move block(s). Use from/to (top-level), fromFlat/toFlat (nested), or fromRef+beforeRef/afterRef (ref-based).",
         inputSchema: {
             type: "object",
             properties: {
@@ -801,6 +2065,11 @@ const tools = [
                 fromFlat: { type: "number", description: "Source flattened index" },
                 toFlat: { type: "number", description: "Target flattened position" },
                 count: { type: "integer", description: "Consecutive count (default: 1)" },
+                snapshotId: { type: "string", description: "Snapshot ID from get_article_structure. Required when using ref." },
+                expectedRevision: { type: "string", description: "Revision from snapshot. Rejects if structure changed." },
+                fromRef: { type: "string", description: "Source block ref (exclusive with from/fromFlat)." },
+                beforeRef: { type: "string", description: "Move before this ref (exclusive with to/toFlat/afterRef)." },
+                afterRef: { type: "string", description: "Move after this ref (exclusive with to/toFlat/beforeRef)." },
             },
         },
     },
@@ -830,13 +2099,16 @@ const tools = [
     },
     {
         name: "duplicate_block",
-        description: "Duplicate block by index or selection.",
+        description: "Duplicate block by index, ref, or selection.",
         inputSchema: {
             type: "object",
             properties: {
                 postId: postIdParam,
                 site: siteParam,
                 index: { type: "number", description: "Index (0-based). Omit for selected." },
+                snapshotId: { type: "string", description: "Snapshot ID from get_article_structure. Required when using ref." },
+                ref: { type: "string", description: "Block ref from snapshot (exclusive with index)." },
+                expectedRevision: { type: "string", description: "Revision from snapshot. Rejects if structure changed." },
             },
         },
     },
@@ -919,7 +2191,7 @@ const tools = [
     },
     {
         name: "insert_block",
-        description: "Insert Gutenberg HTML. Omit index to append.",
+        description: "Insert Gutenberg HTML. Omit index to append. Use beforeRef/afterRef for ref-based positioning.",
         inputSchema: {
             type: "object",
             properties: {
@@ -928,6 +2200,11 @@ const tools = [
                 rawHTML: { type: "string", description: "HTML to insert (exclusive with filePath)" },
                 filePath: { type: "string", description: "Local file path (exclusive with rawHTML)" },
                 index: { type: "number", description: "Position (0-based). Omit to append." },
+                position: { type: "string", enum: ["before", "after"], description: "Insert relative to index: 'before' (default) or 'after'. Requires index." },
+                snapshotId: { type: "string", description: "Snapshot ID. Required when using beforeRef/afterRef." },
+                expectedRevision: { type: "string", description: "Revision from snapshot. Rejects if structure changed." },
+                beforeRef: { type: "string", description: "Insert before this ref (exclusive with index)." },
+                afterRef: { type: "string", description: "Insert after this ref (exclusive with index)." },
             },
         },
     },
@@ -957,13 +2234,59 @@ const tools = [
     },
     {
         name: "update_blocks",
-        description: "Update block(s). Supports replacements, newHTML, or attributeUpdates.",
+        description: "Update block(s). Supports replacements, newHTML, or attributeUpdates. Use ref+snapshotId for safe index resolution.",
         inputSchema: {
             type: "object",
             properties: {
                 postId: postIdParam,
                 site: siteParam,
+                snapshotId: {
+                    type: "string",
+                    description: "Snapshot ID from get_article_structure. Required when using ref/refs in target.",
+                },
+                expectedRevision: {
+                    type: "string",
+                    description: "Revision from snapshot. If provided, rejects update when structure has changed.",
+                },
                 target: targetSchema,
+                operations: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            target: {
+                                type: "object",
+                                properties: {
+                                    ref: { type: "string", description: "Block ref from snapshot (required)." },
+                                },
+                                required: ["ref"],
+                                description: "Batch target: ref only (1 block per operation).",
+                            },
+                            replacements: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        old: { type: "string" },
+                                        new: { type: "string" },
+                                        regex: { type: "boolean" },
+                                    },
+                                    required: ["old", "new"],
+                                },
+                            },
+                            newHTML: { type: "string" },
+                            attributeUpdates: {
+                                type: "object",
+                                properties: {
+                                    filter: { type: "object" },
+                                    set: { type: "object" },
+                                },
+                            },
+                        },
+                        required: ["target"],
+                    },
+                    description: "Batch operations: each targets a single block by ref. Requires snapshotId.",
+                },
                 replacements: {
                     type: "array",
                     items: {
@@ -999,12 +2322,12 @@ const tools = [
                     description: "Preview only",
                 },
             },
-            required: ["target"],
+            // target は operations[] 使用時は不要
         },
     },
     {
         name: "table_operations",
-        description: "Table operations (get/update/add/delete rows/columns/cells).",
+        description: "Table operations (get/update/add/delete rows/columns/cells). Use ref+snapshotId for safe index resolution.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1040,8 +2363,11 @@ const tools = [
                     items: { type: "string" },
                     description: "add_row: new cells, add_column: init values, update_row/column: replacements. Omit for empty.",
                 },
+                snapshotId: { type: "string", description: "Snapshot ID from get_article_structure. Required when using ref." },
+                ref: { type: "string", description: "Block ref from snapshot (exclusive with index)." },
+                expectedRevision: { type: "string", description: "Revision from snapshot. Rejects if structure changed." },
             },
-            required: ["index", "action"],
+            required: ["action"],
         },
     },
     {
@@ -1114,11 +2440,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
  */
 async function handleUpdateBlocksTool(args, toolName) {
     const name = toolName || "update_blocks";
-    let { mode, postId: _postId, sessionId: _sessionId, message, client } = await resolveMode(args, name);
+    let { mode, postId: _postId, sessionId: _sessionId, message, client, siteName } = await resolveMode(args, name);
     if (mode === 'error') {
         return errorResponse(name, message, args?.site);
     }
     const _modeTag = process.env.FRIDAY_DEBUG === '1' ? `\n[DEBUG] mode=${mode}` : '';
+    const _siteName = siteName || args?.site || 'default';
 
     // slug → postId 解決（headless モード時のみ）
     const _resolved = mode === 'headless' ? await resolvePostId(args?.postId, client) : { postId: _postId };
@@ -1140,6 +2467,27 @@ async function handleUpdateBlocksTool(args, toolName) {
         };
     }
 
+    // --- operations[] 排他チェック ---
+    const snapshotId = args?.snapshotId;
+    if (args?.operations && args.operations.length > 0) {
+        const conflicting = ['target', 'replacements', 'newHTML', 'attributeUpdates', 'insert', 'filePath']
+            .filter(k => args[k] !== undefined);
+        if (conflicting.length > 0) {
+            return {
+                content: [{ type: "text", text: `❌ operations と ${conflicting.join(', ')} は同時に指定できません。operations を使う場合、各操作は operations 内に記述してください。` }],
+                isError: true,
+            };
+        }
+        if (!snapshotId) {
+            return {
+                content: [{ type: "text", text: `❌ operations には snapshotId が必要です。get_article_structure で取得してください。` }],
+                isError: true,
+            };
+        }
+        // batch 実行に委譲
+        return await handleBatchOperations(args.operations, snapshotId, mode, client, postId, _sessionId, _siteName, _modeTag, name, args?.expectedRevision);
+    }
+
     // --- normalizeTarget / normalizeInsert ---
     let tp, ins;
     try {
@@ -1149,6 +2497,32 @@ async function handleUpdateBlocksTool(args, toolName) {
         return { content: [{ type: "text", text: `❌ ${e.message}` }], isError: true };
     }
 
+    // --- ref 解決 + revision チェック（共通ヘルパー） ---
+    const resolved = await resolveRefsAndCheckRevision({
+        snapshotId,
+        ref: tp._ref,
+        refs: tp._refs,
+        expectedRevision: args?.expectedRevision,
+        mode, client, postId, sessionId: _sessionId, siteName: _siteName,
+    });
+    if (resolved.error) return resolved.error;
+    const _preState = resolved.currentState || null;  // Phase 2: 差分計算用
+    if (resolved.index !== undefined) {
+        tp.index = resolved.index;
+        delete tp._ref;
+    }
+    if (resolved.indices !== undefined) {
+        tp.indices = resolved.indices;
+        delete tp._refs;
+    }
+
+    // 1→N 展開追跡用の refInfo（単体 ref + newHTML 置換時のみ。insert 系は対象外）
+    const _refInfo = (snapshotId && args?.target?.ref && args?.newHTML && !args?.insert) ? {
+        oldSnapshotId: snapshotId,
+        usedRef: args.target.ref,
+        resolvedIndex: tp.index,
+    } : null;
+
     const { target, index, indices, startIndex, endIndex, section, blockType, typeIndex,
             contains, headingLevel, headingContains } = tp;
     const { insertOnly, insertPosition } = ins;
@@ -1156,6 +2530,17 @@ async function handleUpdateBlocksTool(args, toolName) {
             _fromInsertBlock, appendToEnd } = (args || {});
     let { newHTML } = (args || {});
 
+    // Phase 5: 差分化オプション
+    // - 単体 target.ref かつ snapshotId ありのみ差分化
+    // - appendToEnd は Legacy 固定（早期リターンで自然に除外）
+    const _inputRef = (snapshotId && args?.target?.ref) ? args.target.ref : null;
+    const _isRefInsert = !!(insertOnly && _inputRef);
+
+    // [INSERT_OBSERVE] Step 5: insert_block 経由時の送信パラメータログ
+    if (process.env.FRIDAY_DEBUG === '1' && _fromInsertBlock) {
+        console.log(`[INSERT_OBSERVE] mcp-send: index=${index}, postId=${postId}, sessionId=${_sessionId || 'none'}, mode=${mode}, appendToEnd=${appendToEnd}, htmlLen=${(newHTML || '').length}`);
+    }
+
     // --- filePath → newHTML 解決（update_blocks 直接呼び出し時） ---
     if (args?.filePath) {
         if (newHTML) {
@@ -1196,7 +2581,7 @@ async function handleUpdateBlocksTool(args, toolName) {
         };
     }
 
-    // --- ターゲットチェック（appendToEnd 時は不要） ---
+    // --- ターゲットチェック（appendToEnd / _parentIndex 時は不要） ---
     const hasTarget = target || index !== undefined || indices ||
         startIndex !== undefined || section || blockType || contains ||
         (headingLevel && headingContains);
@@ -1238,7 +2623,8 @@ async function handleUpdateBlocksTool(args, toolName) {
                     _fromInsertBlock: _fromInsertBlock || false,
                 });
                 const count = result.results?.[0]?.count || 1;
-                return { content: [{ type: "text", text: `✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}` }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
             }
 
             const result = await client.headlessUpdate(postId, {
@@ -1263,13 +2649,14 @@ async function handleUpdateBlocksTool(args, toolName) {
                 return { content: [{ type: "text", text: `🔍 プレビュー\n\n対象: ${result.results.length} ブロック\n\n${previewText}${deprecationWarning}` }] };
             }
 
+            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
             if (result.results) {
                 const successCount = result.results.filter(r => r.success).length;
                 const failCount = result.results.filter(r => !r.success).length;
-                return { content: [{ type: "text", text: `✅ 完了\n\n成功: ${successCount} / 失敗: ${failCount}${deprecationWarning}` }] };
+                return { content: [{ type: "text", text: buildUpdateDiffResponse(`✅ 完了\n\n成功: ${successCount} / 失敗: ${failCount}${deprecationWarning}`, _snap, result, _preState, _inputRef, _isRefInsert, _refInfo) }] };
             }
 
-            return { content: [{ type: "text", text: `✅ 更新完了${deprecationWarning}${_modeTag}` }] };
+            return { content: [{ type: "text", text: buildUpdateDiffResponse(`✅ 更新完了${deprecationWarning}${_modeTag}`, _snap, result, _preState, _inputRef, _isRefInsert, _refInfo) }] };
         } catch (e) {
             const formatted = formatHeadlessConflictError(e);
             if (formatted) return formatted;
@@ -1291,7 +2678,8 @@ async function handleUpdateBlocksTool(args, toolName) {
         if (!result || result.timeout) return timeoutResponse(name, client, args?.site);
         if (!result.success) return errorResponse(name, result.error, args?.site);
         const count = result.inserted || 1;
-        return { content: [{ type: "text", text: `✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}` }] };
+        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
     }
 
     // target: "selected" の場合 → エディタ状態から選択情報を取得してMCP側で処理
@@ -1344,7 +2732,10 @@ async function handleUpdateBlocksTool(args, toolName) {
                 return timeoutResponse(name, client, args?.site);
             if (!result.success)
                 return errorResponse(name, result.error, args?.site);
-            return { content: [{ type: "text", text: `✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${hasTextSelection ? "（カーソル選択モード）" : "（差分）"}${deprecationWarning}` }] };
+            {
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${hasTextSelection ? "（カーソル選択モード）" : "（差分）"}${deprecationWarning}`, _snap, _refInfo) }] };
+            }
         }
 
         // newHTMLの場合
@@ -1360,7 +2751,10 @@ async function handleUpdateBlocksTool(args, toolName) {
                 return timeoutResponse(name, client, args?.site);
             if (!result.success)
                 return errorResponse(name, result.error, args?.site);
-            return { content: [{ type: "text", text: `✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}` }] };
+            {
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}`, _snap, _refInfo) }] };
+            }
         }
 
         // attributeUpdatesの場合
@@ -1374,12 +2768,15 @@ async function handleUpdateBlocksTool(args, toolName) {
             return timeoutResponse(name, client, args?.site);
         if (!result.success)
             return errorResponse(name, result.error, args?.site);
-        return { content: [{ type: "text", text: `✅ 属性更新完了${deprecationWarning}` }] };
+        {
+            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+            return { content: [{ type: "text", text: appendSnapshotToTextLegacy(`✅ 属性更新完了${deprecationWarning}`, _snap, _refInfo) }] };
+        }
     }
 
     // その他のターゲット → 全てWP側で解決＆実行
     const maxWait = (section || blockType || contains) ? 15000 : 10000;
-    const result = await client.sendEditorCommand("update_blocks", {
+    const editorParams = {
         index, indices, startIndex, endIndex,
         section, blockType, typeIndex, contains,
         headingLevel, headingContains,
@@ -1388,7 +2785,8 @@ async function handleUpdateBlocksTool(args, toolName) {
         insertPosition,
         dryRun: dryRun || false,
         _fromInsertBlock: _fromInsertBlock || false,
-    }, maxWait, _postId, _sessionId);
+    };
+    const result = await client.sendEditorCommand("update_blocks", editorParams, maxWait, _postId, _sessionId);
     if (!result || result.timeout)
         return timeoutResponse(name, client, args?.site);
     if (!result.success)
@@ -1412,15 +2810,16 @@ async function handleUpdateBlocksTool(args, toolName) {
         return { content: [{ type: "text", text: `🔍 プレビュー\n\n対象: ${result.results.length} ブロック\n\n${previewText || "(対象なし)"}${deprecationWarning}` }] };
     }
 
+    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
     if (result.results) {
         const successCount = result.results.filter(r => r.success && !r.skipped).length;
         const skipCount = result.results.filter(r => r.skipped).length;
         const failCount = result.results.filter(r => !r.success).length;
         const detailText = result.results.filter(r => r.success && r.replaceCount > 0).map(r => `  [${r.index}]: ${r.replaceCount}箇所`).join('\n');
-        return { content: [{ type: "text", text: `✅ 完了\n\n成功: ${successCount} / スキップ: ${skipCount} / 失敗: ${failCount}\n\n${detailText}${deprecationWarning}${_modeTag}` }] };
+        return { content: [{ type: "text", text: buildUpdateDiffResponse(`✅ 完了\n\n成功: ${successCount} / スキップ: ${skipCount} / 失敗: ${failCount}\n\n${detailText}${deprecationWarning}${_modeTag}`, _snap, result, _preState, _inputRef, _isRefInsert, _refInfo) }] };
     }
 
-    return { content: [{ type: "text", text: `✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}${_modeTag}` }] };
+    return { content: [{ type: "text", text: buildUpdateDiffResponse(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}${_modeTag}`, _snap, result, _preState, _inputRef, _isRefInsert, _refInfo) }] };
 }
 
 // ツール実行のハンドラ
@@ -1475,6 +2874,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     state = await client.getEditorState(_postId, _sessionId);
                 }
 
+                // --- snapshot 作成（allBlocks がある場合のみ） ---
+                let _refTag = (_idx, _prefix) => '';
+                let _snapshotLine = '';
+
+                if (state.allBlocks && state.allBlocks.length > 0) {
+                    const snapshotId = generateSnapshotId();
+                    const snapshotBlocks = buildSnapshotBlocks(state, mode);
+                    const revision = computeRevision(state, mode);
+                    const snapshotRecord = {
+                        snapshotId, postId, mode,
+                        sessionId: mode === 'editor' ? _sessionId : null,
+                        siteName: siteName || 'default',
+                        createdAt: Date.now(),
+                        revision,
+                        blocks: snapshotBlocks,
+                        displayMode: full ? 'full' : contains ? 'contains' : section ? (blockType ? 'section+blockType' : 'section') : blockType ? 'blockType' : headingLevel ? 'headingLevel' : 'default',
+                    };
+                    snapshotCache.set(snapshotRecord);
+
+                    const _refMap = new Map(snapshotBlocks.map(b => [b.index, b.ref]));
+                    _refTag = (idx, prefix = '|') => { const r = _refMap.get(idx); return r ? `${prefix}${r}` : ''; };
+                    _snapshotLine = `\n[snapshot:${snapshotId} rev:${revision}]`;
+                }
+
+                // ツリー構造情報のフォーマットヘルパー
+                function formatTreeLine(b) {
+                    const depth = b.depth || 0;
+                    const indent = '  '.repeat(depth + 1);
+                    let marker = '';
+                    let childInfo = '';
+                    if (b.isContainer) {
+                        marker = '▼ ';
+                        if (b.columnCount) childInfo = ` [${b.columnCount}カラム]`;
+                        else if (b.tabNames && b.tabNames.length > 0) childInfo = ` [${b.tabNames.join(", ")}]`;
+                        else if (b.childCount) childInfo = ` [${b.childCount}子]`;
+                    }
+                    const parentInfo = (depth > 0 && b.parentIndex != null) ? `, p:${b.parentIndex}` : '';
+                    return { indent, marker, childInfo, depthInfo: `(d:${depth}${parentInfo})` };
+                }
+
                 // ========================================
                 // 全ブロック情報取得（full=true）
                 // ========================================
@@ -1505,7 +2944,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                     const blockList = blocks.map(b => {
                         const attrPreview = JSON.stringify(b.attributes || {}).slice(0, 200);
-                        return `  [${b.index}] ${b.type} - ${b.section || "(記事冒頭)"} (d:${b.depth})\n    ${attrPreview}${attrPreview.length >= 200 ? '...' : ''}`;
+                        const t = formatTreeLine(b);
+                        return `${t.indent}[${b.index}${_refTag(b.index)}] ${t.marker}${b.type}${t.childInfo} - ${b.section || "(記事冒頭)"} ${t.depthInfo}\n${t.indent}  ${attrPreview}${attrPreview.length >= 200 ? '...' : ''}`;
                     }).join("\n\n");
 
                     let paginationInfo = '';
@@ -1519,7 +2959,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return {
                         content: [{
                             type: "text",
-                            text: `📊 get_article_structure(${paramLabel})\n\n全ブロック情報 (${blocks.length}件):\n\n${blockList}${paginationInfo}${_modeTag_gas}`,
+                            text: `📊 get_article_structure(${paramLabel})\n\n全ブロック情報 (${blocks.length}件):\n\n${blockList}${paginationInfo}${_snapshotLine}${_modeTag_gas}`,
                         }],
                     };
                 }
@@ -1556,6 +2996,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                     type: block.type,
                                     section: block.section,
                                     depth: block.depth,
+                                    parentIndex: block.parentIndex,
+                                    isContainer: block.isContainer,
+                                    childCount: block.childCount,
                                     preview: preview
                                 });
                             }
@@ -1572,9 +3015,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                         const matchList = matches
                             .map(m => {
-                                let line = `  index ${m.index}: ${m.type} - ${m.section || "(記事冒頭)"} (d:${m.depth})`;
+                                const t = formatTreeLine(m);
+                                let line = `${t.indent}index ${m.index}${_refTag(m.index, ' ')}: ${t.marker}${m.type}${t.childInfo} - ${m.section || "(記事冒頭)"} ${t.depthInfo}`;
                                 if (m.preview) {
-                                    line += `\n    "${m.preview}"`;
+                                    line += `\n${t.indent}  "${m.preview}"`;
                                 }
                                 return line;
                             })
@@ -1583,7 +3027,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         return {
                             content: [{
                                 type: "text",
-                                text: `📊 get_article_structure(${paramLabel})\n\n"${contains}" を含むブロック (${matches.length}個):\n\n${matchList}${_modeTag_gas}`,
+                                text: `📊 get_article_structure(${paramLabel})\n\n"${contains}" を含むブロック (${matches.length}個):\n\n${matchList}${_snapshotLine}${_modeTag_gas}`,
                             }],
                         };
                     }
@@ -1613,9 +3057,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                         const matchList = (searchResult.matches || [])
                             .map(m => {
-                                let line = `  index ${m.index}: ${m.type} - ${m.section || "(記事冒頭)"} (d:${m.depth})`;
+                                const t = formatTreeLine(m);
+                                let line = `${t.indent}index ${m.index}${_refTag(m.index, ' ')}: ${t.marker}${m.type}${t.childInfo} - ${m.section || "(記事冒頭)"} ${t.depthInfo}`;
                                 if (m.preview) {
-                                    line += `\n    "${m.preview}"`;
+                                    line += `\n${t.indent}  "${m.preview}"`;
                                 }
                                 return line;
                             })
@@ -1624,7 +3069,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         return {
                             content: [{
                                 type: "text",
-                                text: `📊 get_article_structure(${paramLabel})\n\n"${contains}" を含むブロック (${(searchResult.matches || []).length}個):\n\n${matchList}${_modeTag_gas}`,
+                                text: `📊 get_article_structure(${paramLabel})\n\n"${contains}" を含むブロック (${(searchResult.matches || []).length}個):\n\n${matchList}${_snapshotLine}${_modeTag_gas}`,
                             }],
                         };
                     }
@@ -1698,12 +3143,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
 
                     const blockList = filteredBlocks
-                        .map(b => `  index ${b.index}: d:${b.depth || 0}`)
+                        .map(b => {
+                            const t = formatTreeLine(b);
+                            return `${t.indent}index ${b.index}${_refTag(b.index, ' ')}: ${t.marker}${blockType}${t.childInfo} ${t.depthInfo}`;
+                        })
                         .join("\n");
                     return {
                         content: [{
                             type: "text",
-                            text: `📊 get_article_structure(${paramLabel})\n\n${sectionHeading.text} セクション内の ${blockType} (${filteredBlocks.length}個):\n\n${blockList}${_modeTag_gas}`,
+                            text: `📊 get_article_structure(${paramLabel})\n\n${sectionHeading.text} セクション内の ${blockType} (${filteredBlocks.length}個):\n\n${blockList}${_snapshotLine}${_modeTag_gas}`,
                         }],
                     };
                 }
@@ -1723,19 +3171,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const typeData = state.blockSummary[blockType];
                     const blockList = typeData.blocks
                         .map(b => {
-                            let info = `  index ${b.index}: ${b.section || "(記事冒頭)"} (H${b.sectionLevel || "-"}) d:${b.depth || 0}`;
-                            if (b.tabNames && b.tabNames.length > 0) {
-                                info += ` [${b.tabNames.join(", ")}]`;
-                            } else if (b.columnCount) {
-                                info += ` [${b.columnCount}カラム]`;
-                            }
-                            return info;
+                            const t = formatTreeLine(b);
+                            return `${t.indent}index ${b.index}${_refTag(b.index, ' ')}: ${t.marker}${b.section || "(記事冒頭)"} (H${b.sectionLevel || "-"})${t.childInfo} ${t.depthInfo}`;
                         })
                         .join("\n");
                     return {
                         content: [{
                             type: "text",
-                            text: `📊 get_article_structure(${paramLabel})\n\n${blockType} の一覧 (${typeData.count}個):\n\n${blockList}${_modeTag_gas}`,
+                            text: `📊 get_article_structure(${paramLabel})\n\n${blockType} の一覧 (${typeData.count}個):\n\n${blockList}${_snapshotLine}${_modeTag_gas}`,
                         }],
                     };
                 }
@@ -1793,20 +3236,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
                     const blockList = sectionBlocks
                         .map(b => {
-                            const indent = '  '.repeat((b.depth || 0) + 1);
-                            let marker = '';
-                            let info = '';
-                            if (b.isContainer) {
-                                marker = '▼ ';
-                                if (b.columnCount) {
-                                    info = ` [${b.columnCount}カラム]`;
-                                } else if (b.tabNames && b.tabNames.length > 0) {
-                                    info = ` [${b.tabNames.join(", ")}]`;
-                                } else if (b.childCount) {
-                                    info = ` [${b.childCount}子]`;
-                                }
-                            }
-                            return `${indent}${b.index}: ${marker}${b.type}${info} (d:${b.depth || 0})`;
+                            const t = formatTreeLine(b);
+                            return `${t.indent}${b.index}${_refTag(b.index, ' ')}: ${t.marker}${b.type}${t.childInfo} ${t.depthInfo}`;
                         })
                         .join("\n");
 
@@ -1817,7 +3248,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return {
                         content: [{
                             type: "text",
-                            text: `📊 get_article_structure(${paramLabel})\n\n${sectionHeading.text} セクション (index:${sectionHeading.index}):\n\n${blockList}${nextInfo}${_modeTag_gas}`,
+                            text: `📊 get_article_structure(${paramLabel})\n\n${sectionHeading.text} セクション (index:${sectionHeading.index}):\n\n${blockList}${nextInfo}${_snapshotLine}${_modeTag_gas}`,
                         }],
                     };
                 }
@@ -1836,12 +3267,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         };
                     }
                     const headingList = filteredHeadings
-                        .map(h => `  ${"#".repeat(h.level)} ${h.text} (index:${h.index})`)
+                        .map(h => `  ${"#".repeat(h.level)} ${h.text} (index:${h.index}${_refTag(h.index)})`)
                         .join("\n");
                     return {
                         content: [{
                             type: "text",
-                            text: `📊 get_article_structure(${paramLabel})\n\nH${headingLevel}見出し一覧 (${filteredHeadings.length}個):\n\n${headingList}${_modeTag_gas}`,
+                            text: `📊 get_article_structure(${paramLabel})\n\nH${headingLevel}見出し一覧 (${filteredHeadings.length}個):\n\n${headingList}${_snapshotLine}${_modeTag_gas}`,
                         }],
                     };
                 }
@@ -1854,11 +3285,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 for (const heading of state.headings) {
                     const indent = heading.level === 2 ? "" : "  ";
                     const prefix = "#".repeat(heading.level);
-                    output += `${indent}${prefix} ${heading.text} (H${heading.level}, index:${heading.index})\n`;
+                    output += `${indent}${prefix} ${heading.text} (H${heading.level}, index:${heading.index}${_refTag(heading.index)})\n`;
                 }
 
                 return {
-                    content: [{ type: "text", text: output + _modeTag_gas }],
+                    content: [{ type: "text", text: output + _snapshotLine + _modeTag_gas }],
                 };
             }
 
@@ -1916,7 +3347,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
 
             case "delete_block": {
-                let { mode, postId: _postId, sessionId: _sessionId, message, client } = await resolveMode(args, name);
+                let { mode, postId: _postId, sessionId: _sessionId, message, client, siteName } = await resolveMode(args, name);
                 if (mode === 'error') {
                     return errorResponse(name, message, args?.site);
                 }
@@ -1925,13 +3356,35 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (_resolved.editorConnected) mode = 'editor';
                 const postId = _resolved.postId ?? _postId;
                 const _mt_db = process.env.FRIDAY_DEBUG === '1' ? `\n[DEBUG] mode=${mode}` : '';
+                const _siteName = siteName || args?.site || 'default';
 
                 if (mode === 'headless') {
                     const _guard = await guardHeadlessConflict(postId, client, name);
                     if (_guard) return _guard;
                 }
 
-                const { index, count, indices } = args;
+                // ref/refs と index/indices 排他チェック
+                if ((args?.ref || args?.refs) && (args?.index !== undefined || args?.indices !== undefined)) {
+                    return { content: [{ type: "text", text: "❌ ref/refs と index/indices は同時に指定できません。" }], isError: true };
+                }
+
+                // ref 解決 + revision チェック
+                const resolved = await resolveRefsAndCheckRevision({
+                    snapshotId: args?.snapshotId, ref: args?.ref, refs: args?.refs,
+                    expectedRevision: args?.expectedRevision,
+                    mode, client, postId, sessionId: _sessionId, siteName: _siteName,
+                });
+                if (resolved.error) return resolved.error;
+                const _preState = resolved.currentState || null;  // Phase 2: 差分計算用
+
+                let { index, count, indices } = args;
+                if (resolved.index !== undefined) { index = resolved.index; count = count || 1; }
+                if (resolved.indices !== undefined) { indices = resolved.indices; }
+
+                // Phase 3: 入力 ref を保持（ref + count > 1 は差分化できないので Legacy）
+                const _inputRefs = args?.refs ? [...new Set(args.refs)]
+                    : (args?.ref && (count || 1) <= 1) ? [args.ref]
+                    : null;
 
                 // indices と index/count の排他バリデーション
                 if (indices !== undefined && (index !== undefined || count !== undefined)) {
@@ -1953,7 +3406,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         try {
                             const result = await client.headlessDeleteMultiple(postId, uniqueIndices);
                             const details = result.deleted.map(d => `  [${d.index}] ${d.type}`).join('\n');
-                            return { content: [{ type: "text", text: `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}` }] };
+                            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                            const _msg = `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`;
+                            if (_inputRefs) {
+                                const changeInfo = buildChangeInfoFromResult('deleted', _snap, result, _preState, { inputRefs: _inputRefs });
+                                if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                            }
+                            return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                         } catch (e) {
                             const formatted = formatHeadlessConflictError(e);
                             if (formatted) return formatted;
@@ -1967,7 +3426,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     if (!result.success)
                         return errorResponse(name, result.error, args?.site);
                     const details = result.deleted.map(d => `  [${d.index}] ${d.type}`).join('\n');
-                    return { content: [{ type: "text", text: `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}` }] };
+                    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                    const _msg = `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`;
+                    if (_inputRefs) {
+                        const changeInfo = buildChangeInfoFromResult('deleted', _snap, result, _preState, { inputRefs: _inputRefs });
+                        if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                    }
+                    return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                 }
 
                 // 既存モード（index + count）
@@ -1978,7 +3443,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     try {
                         const result = await client.headlessDelete(postId, index, count || 1);
                         const details = result.deleted.map(d => `  [${d.index}] ${d.type}`).join('\n');
-                        return { content: [{ type: "text", text: `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}` }] };
+                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                        const _msg = `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`;
+                        if (_inputRefs) {
+                            const changeInfo = buildChangeInfoFromResult('deleted', _snap, result, _preState, { inputRefs: _inputRefs });
+                            if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                        }
+                        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -1992,11 +3463,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!result.success)
                     return errorResponse(name, result.error, args?.site);
                 const details = result.deleted.map(d => `  [${d.index}] ${d.type}`).join('\n');
-                return { content: [{ type: "text", text: `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}` }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                const _msg = `✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`;
+                if (_inputRefs) {
+                    const changeInfo = buildChangeInfoFromResult('deleted', _snap, result, _preState, { inputRefs: _inputRefs });
+                    if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                }
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
             }
 
             case "move_block": {
-                let { mode, postId: _postId, sessionId: _sessionId, message, client } = await resolveMode(args, name);
+                let { mode, postId: _postId, sessionId: _sessionId, message, client, siteName } = await resolveMode(args, name);
                 if (mode === 'error') {
                     return errorResponse(name, message, args?.site);
                 }
@@ -2005,13 +3482,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (_resolved.editorConnected) mode = 'editor';
                 const postId = _resolved.postId ?? _postId;
                 const _mt_mb = process.env.FRIDAY_DEBUG === '1' ? `\n[DEBUG] mode=${mode}` : '';
+                const _siteName = siteName || args?.site || 'default';
 
                 if (mode === 'headless') {
                     const _guard = await guardHeadlessConflict(postId, client, name);
                     if (_guard) return _guard;
                 }
 
-                const { from, to, fromFlat, toFlat } = args;
+                const { from, to } = args;
+                let { fromFlat, toFlat } = args;
                 const count = args.count ?? 1;
 
                 // count バリデーション
@@ -2019,16 +3498,71 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return { content: [{ type: "text", text: "❌ count は1以上の整数を指定してください。" }], isError: true };
                 }
 
-                // 排他バリデーション
+                // 3 モード排他バリデーション
                 const hasTopLevel = from !== undefined || to !== undefined;
                 const hasFlat = fromFlat !== undefined || toFlat !== undefined;
-                if (hasTopLevel && hasFlat) {
-                    return { content: [{ type: "text", text: "❌ from/to と fromFlat/toFlat は同時に指定できません。" }], isError: true };
+                const hasRef = args?.fromRef !== undefined || args?.beforeRef !== undefined || args?.afterRef !== undefined;
+                const _modeCount = [hasTopLevel, hasFlat, hasRef].filter(Boolean).length;
+
+                if (_modeCount > 1) {
+                    return { content: [{ type: "text", text: "❌ from/to, fromFlat/toFlat, ref(fromRef/beforeRef/afterRef) は同時に指定できません。" }], isError: true };
+                }
+                if (_modeCount === 0) {
+                    return { content: [{ type: "text", text: "❌ from/to, fromFlat/toFlat, または fromRef+beforeRef/afterRef を指定してください。" }], isError: true };
+                }
+
+                // expectedRevision チェック（全モード共通）
+                // ref モード以外でも expectedRevision が指定されていれば revision チェックを実施
+                let _preState = null;  // Phase 2: 差分計算用
+                if (args?.expectedRevision && !hasRef) {
+                    const { currentState, error: _revError } = await acquireFreshState({
+                        expectedRevision: args.expectedRevision,
+                        mode, client, postId, sessionId: _sessionId, siteName: _siteName,
+                    });
+                    if (_revError) return _revError;
+                    _preState = currentState || null;
                 }
-                if (!hasTopLevel && !hasFlat) {
-                    return { content: [{ type: "text", text: "❌ from/to または fromFlat/toFlat を指定してください。" }], isError: true };
+
+                // ref モード: fromRef + beforeRef/afterRef
+                if (hasRef) {
+                    if (!args.fromRef) {
+                        return { content: [{ type: "text", text: "❌ ref モードでは fromRef が必須です。" }], isError: true };
+                    }
+                    if (!args.beforeRef && !args.afterRef) {
+                        return { content: [{ type: "text", text: "❌ ref モードでは beforeRef または afterRef が必須です。" }], isError: true };
+                    }
+                    if (args.beforeRef && args.afterRef) {
+                        return { content: [{ type: "text", text: "❌ beforeRef と afterRef は同時に指定できません。" }], isError: true };
+                    }
+                    if (!args.snapshotId) {
+                        return { content: [{ type: "text", text: "❌ ref を使用するには snapshotId が必要です。get_article_structure で取得してください。" }], isError: true };
+                    }
+
+                    // acquireFreshState で 1 回だけ state 取得 + revision チェック
+                    const { currentState, error: _stateError } = await acquireFreshState({
+                        expectedRevision: args.expectedRevision,
+                        mode, client, postId, sessionId: _sessionId, siteName: _siteName,
+                    });
+                    if (_stateError) return _stateError;
+                    _preState = currentState || null;  // Phase 2: 差分計算用
+
+                    // ref 解決（同じ currentState で 2 つの ref を解決）
+                    try {
+                        fromFlat = resolveRefFromState(args.snapshotId, args.fromRef, mode, _sessionId, postId, currentState);
+                        const destRef = args.beforeRef || args.afterRef;
+                        const resolvedDest = resolveRefFromState(args.snapshotId, destRef, mode, _sessionId, postId, currentState);
+                        // 位置計算: beforeRef → そのまま, afterRef → +1
+                        toFlat = args.beforeRef ? resolvedDest : resolvedDest + 1;
+                    } catch (e) {
+                        return { content: [{ type: "text", text: `❌ ref 解決エラー: ${e.message}` }], isError: true };
+                    }
+
+                    // ref → flat に変換完了。以降 flat モードに合流
                 }
 
+                // Phase 4: 入力 ref 保持（ref モード + count <= 1 のみ差分化）
+                const _inputRefs = (hasRef && count <= 1) ? [args.fromRef] : null;
+
                 // 移動結果のレスポンス生成ヘルパー
                 const moveMsg = (moved) => {
                     if (moved?.noop) return `✅ 移動不要（同じ位置）${_mt_mb}`;
@@ -2039,8 +3573,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         : `✅ ブロック移動 (${typeLabel})${_mt_mb}`;
                 };
 
-                // fromFlat/toFlat モード（フラットインデックス移動）
-                if (hasFlat) {
+                // fromFlat/toFlat モード（フラットインデックス移動）— ref モードもここに合流
+                if (hasFlat || hasRef) {
                     if (fromFlat === undefined || toFlat === undefined) {
                         return { content: [{ type: "text", text: "❌ fromFlat と toFlat の両方を指定してください。" }], isError: true };
                     }
@@ -2051,7 +3585,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     if (mode === 'headless') {
                         try {
                             const result = await client.headlessMoveFlat(postId, fromFlat, toFlat, count);
-                            return { content: [{ type: "text", text: moveMsg(result.moved) }] };
+                            const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                            const _msg = moveMsg(result.moved);
+                            if (_inputRefs) {
+                                const changeInfo = buildChangeInfoFromResult('moved', _snap, result, _preState, { inputRefs: _inputRefs });
+                                if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                            }
+                            return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                         } catch (e) {
                             const formatted = formatHeadlessConflictError(e);
                             if (formatted) return formatted;
@@ -2064,7 +3604,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         return timeoutResponse(name, client, args?.site);
                     if (!result.success)
                         return errorResponse(name, result.error, args?.site);
-                    return { content: [{ type: "text", text: moveMsg(result.moved) }] };
+                    const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                    const _msg = moveMsg(result.moved);
+                    if (_inputRefs) {
+                        const changeInfo = buildChangeInfoFromResult('moved', _snap, result, _preState, { inputRefs: _inputRefs });
+                        if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                    }
+                    return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                 }
 
                 // 既存モード（from/to トップレベル）
@@ -2075,7 +3621,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (mode === 'headless') {
                     try {
                         const result = await client.headlessMove(postId, from, to, count);
-                        return { content: [{ type: "text", text: moveMsg(result.moved) }] };
+                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(moveMsg(result.moved), _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -2088,7 +3635,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return timeoutResponse(name, client, args?.site);
                 if (!result.success)
                     return errorResponse(name, result.error, args?.site);
-                return { content: [{ type: "text", text: moveMsg(result.moved) }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(moveMsg(result.moved), _snap) }] };
             }
 
             case "undo": {
@@ -2124,7 +3672,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
 
             case "duplicate_block": {
-                let { mode, postId: _postId, sessionId: _sessionId, message, client } = await resolveMode(args, name);
+                let { mode, postId: _postId, sessionId: _sessionId, message, client, siteName } = await resolveMode(args, name);
                 if (mode === 'error') {
                     return errorResponse(name, message, args?.site);
                 }
@@ -2133,8 +3681,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (_resolved.editorConnected) mode = 'editor';
                 const postId = _resolved.postId ?? _postId;
                 const _mt_dup = process.env.FRIDAY_DEBUG === '1' ? `\n[DEBUG] mode=${mode}` : '';
+                const _siteName = siteName || args?.site || 'default';
+
+                // ref と index 排他チェック
+                if (args?.ref && args?.index !== undefined) {
+                    return { content: [{ type: "text", text: "❌ ref と index は同時に指定できません。" }], isError: true };
+                }
 
-                const { index } = args;
+                // ref 解決 + revision チェック
+                const resolved = await resolveRefsAndCheckRevision({
+                    snapshotId: args?.snapshotId, ref: args?.ref,
+                    expectedRevision: args?.expectedRevision,
+                    mode, client, postId, sessionId: _sessionId, siteName: _siteName,
+                });
+                if (resolved.error) return resolved.error;
+                const _preState = resolved.currentState || null;  // Phase 2: 差分計算用
+
+                const index = resolved.index !== undefined ? resolved.index : args?.index;
+
+                // Phase 3: 入力 ref を保持（index 経路は差分化しない）
+                const _inputRef = args?.ref || null;
 
                 if (mode === 'headless') {
                     const _guard = await guardHeadlessConflict(postId, client, name);
@@ -2144,7 +3710,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                     try {
                         const result = await client.headlessDuplicate(postId, index);
-                        return { content: [{ type: "text", text: `✅ ブロック複製完了 (index ${result.duplicated.index} → ${result.duplicated.newIndex})${_mt_dup}` }] };
+                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                        const _msg = `✅ ブロック複製完了 (index ${result.duplicated.index} → ${result.duplicated.newIndex})${_mt_dup}`;
+                        if (_inputRef) {
+                            const changeInfo = buildChangeInfoFromResult('duplicated', _snap, result, _preState, { inputRef: _inputRef });
+                            if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                        }
+                        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -2157,7 +3729,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return timeoutResponse(name, client, args?.site);
                 if (!result.success)
                     return errorResponse(name, result.error, args?.site);
-                return { content: [{ type: "text", text: `✅ ブロック複製完了${_mt_dup}` }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                const _msg = `✅ ブロック複製完了${_mt_dup}`;
+                if (_inputRef) {
+                    const changeInfo = buildChangeInfoFromResult('duplicated', _snap, result, _preState, { inputRef: _inputRef });
+                    if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                }
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
             }
 
             case "save_post": {
@@ -2362,13 +3940,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
 
             case "insert_block": {
-                let { rawHTML, filePath, index } = (args || {});
+                let { rawHTML, filePath, index, position } = (args || {});
+
+                // parentIndex は廃止済み（v3.0.0 Phase 5）— position を使用
+                if (args?.parentIndex !== undefined) {
+                    return { content: [{ type: "text", text: "❌ parentIndex は廃止されました。代わりに index + position ('before'/'after') を使用してください。" }], isError: true };
+                }
 
                 // 排他チェック
                 if (rawHTML && filePath) {
                     return { content: [{ type: "text", text: "❌ rawHTML と filePath は同時に指定できません。どちらか一方を指定してください。" }], isError: true };
                 }
 
+                // Phase 4b: beforeRef/afterRef と index/position の排他チェック
+                const _hasRefPosition = args?.beforeRef !== undefined || args?.afterRef !== undefined;
+                const _hasIndexPosition = index !== undefined || position !== undefined;
+                if (_hasRefPosition && _hasIndexPosition) {
+                    return { content: [{ type: "text", text: "❌ beforeRef/afterRef と index/position は同時に指定できません。" }], isError: true };
+                }
+                if (args?.beforeRef && args?.afterRef) {
+                    return { content: [{ type: "text", text: "❌ beforeRef と afterRef は同時に指定できません。" }], isError: true };
+                }
+
+                // position 指定時は index 必須（ref モードでないとき）
+                if (!_hasRefPosition && position !== undefined && index === undefined) {
+                    return { content: [{ type: "text", text: "❌ position を指定する場合は index も指定してください。末尾追加は index を省略してください。" }], isError: true };
+                }
+
+                // position バリデーション
+                if (position !== undefined && position !== "before" && position !== "after") {
+                    return { content: [{ type: "text", text: `❌ position は 'before' または 'after' を指定してください: ${position}` }], isError: true };
+                }
+
                 // filePath → rawHTML 解決
                 if (filePath) {
                     try { rawHTML = readHTMLFromFile(filePath).html; }
@@ -2378,21 +3981,39 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return { content: [{ type: "text", text: "❌ rawHTML または filePath を指定してください。Gutenberg HTML 形式のブロックマークアップが必要です。" }], isError: true };
                 }
 
-                // index バリデーション（現行 Editor 互換: 整数 >= 0）
-                if (index !== undefined && (!Number.isInteger(index) || index < 0)) {
+                // index バリデーション（現行 Editor 互換: 整数 >= 0）— ref モードでないとき
+                if (!_hasRefPosition && index !== undefined && (!Number.isInteger(index) || index < 0)) {
                     return { content: [{ type: "text", text: `❌ Invalid index: ${index}` }], isError: true };
                 }
 
-                // update_blocks コードパスに委譲（新形式 target/insert を使用）
+                // update_blocks コードパスに委譲
+                // expectedRevision は全モードで委譲（ref/index/append 問わず）
                 const delegatedArgs = {
                     postId: args.postId,
                     site: args.site,
                     newHTML: rawHTML,
-                    insert: { position: 'before' },
                     _fromInsertBlock: true,
-                    appendToEnd: index === undefined,
+                    expectedRevision: args.expectedRevision,
                 };
-                if (index !== undefined) delegatedArgs.target = { index };
+
+                if (_hasRefPosition) {
+                    // ref モード: target.ref + insert.position で委譲
+                    const _ref = args.beforeRef || args.afterRef;
+                    delegatedArgs.target = { ref: _ref };
+                    delegatedArgs.insert = { position: args.beforeRef ? 'before' : 'after' };
+                    delegatedArgs.snapshotId = args.snapshotId;
+                    delegatedArgs.appendToEnd = false;
+                } else if (index !== undefined) {
+                    // 既存: index モード
+                    delegatedArgs.target = { index };
+                    delegatedArgs.insert = { position: position ?? 'before' };
+                    delegatedArgs.appendToEnd = false;
+                } else {
+                    // 末尾追加
+                    delegatedArgs.insert = { position: 'before' };
+                    delegatedArgs.appendToEnd = true;
+                }
+
                 return await handleUpdateBlocksTool(delegatedArgs, name);
             }
 
@@ -2468,7 +4089,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
 
             case "get_selection": {
-                const { mode, postId: _postId, sessionId: _sessionId, message, client } = await resolveMode(args, name);
+                const { mode, postId: _postId, sessionId: _sessionId, message, client, siteName } = await resolveMode(args, name);
                 if (mode === 'error') {
                     return errorResponse(name, message, args?.site);
                 }
@@ -2484,16 +4105,48 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         content: [{ type: "text", text: `ブロックが選択されていません。${_mt_gs}` }],
                     };
                 }
+
+                // ref 対応: fresh state から snapshot を毎回新規作成
+                // safetyCritical: true — stale Store へのフォールバックを防ぐ
+                const _siteName_gs = siteName || args?.site || 'default';
+                let _snapInfo = null;
+                try {
+                    const freshState = await getCurrentStructure(mode, client, _postId, _sessionId, { safetyCritical: true });
+                    if (freshState?.allBlocks?.length > 0) {
+                        _snapInfo = buildSnapshotFromState(freshState, mode, _postId, _sessionId, _siteName_gs);
+                    }
+                } catch (_e) {
+                    // fresh state 取得失敗 → ref なしで index-only にフォールバック
+                }
+
                 // 複数選択
                 if (sel.isMultiSelect && sel.blockIds) {
                     let text = `選択中: ${sel.blockIds.length}ブロック\n` +
                         `タイプ: ${sel.blockTypes?.join(", ")}\n` +
-                        `位置: ${sel.blockIndices?.join(", ")}${_mt_gs}`;
+                        `位置: ${sel.blockIndices?.join(", ")}`;
+                    if (_snapInfo && sel.blockIndices?.length > 0) {
+                        const refs = sel.blockIndices
+                            .map(idx => _snapInfo.blocks?.find(b => b.index === idx)?.ref)
+                            .filter(Boolean);
+                        // 全数一致のときだけ refs を返す（部分一致は AI を誤誘導するため）
+                        if (refs.length === sel.blockIndices.length) {
+                            text += `\nrefs: ${refs.join(", ")}`;
+                            text += `\n[snapshot:${_snapInfo.snapshotId} rev:${_snapInfo.revision}]`;
+                        }
+                    }
+                    text += _mt_gs;
                     return { content: [{ type: "text", text }] };
                 }
                 // 単一選択
                 let text = `選択中: ${sel.blockType}\n` +
                     `位置: index ${sel.blockIndex}`;
+                if (_snapInfo) {
+                    const refEntry = _snapInfo.blocks?.find(b => b.index === sel.blockIndex);
+                    if (refEntry) {
+                        text += `\nref: ${refEntry.ref}`;
+                        text += `\n[snapshot:${_snapInfo.snapshotId} rev:${_snapInfo.revision}]`;
+                    }
+                }
                 if (sel.textSelection?.text) {
                     text += `\n\nカーソル選択テキスト: "${sel.textSelection.text}"`;
                     if (sel.textSelection.context) {
@@ -2510,7 +4163,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
 
             case "table_operations": {
-                let { mode, postId: _postId, sessionId: _sessionId, message, client } = await resolveMode(args, name);
+                let { mode, postId: _postId, sessionId: _sessionId, message, client, siteName } = await resolveMode(args, name);
                 if (mode === 'error') {
                     return errorResponse(name, message, args?.site);
                 }
@@ -2518,15 +4171,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (_resolved.error) return { content: [{ type: "text", text: _resolved.error }], isError: true };
                 if (_resolved.editorConnected) mode = 'editor';
                 const postId = _resolved.postId ?? _postId;
+                const _siteName = siteName || args?.site || 'default';
 
-                const { index, action } = (args || {});
-                if (index === undefined) {
-                    return { content: [{ type: "text", text: "❌ index は必須です" }], isError: true };
-                }
+                const { action } = (args || {});
+                const _inputRef = args?.ref || null;
                 if (!action) {
                     return { content: [{ type: "text", text: "❌ action は必須です" }], isError: true };
                 }
 
+                // ref と index 排他チェック
+                if (args?.ref && args?.index !== undefined) {
+                    return { content: [{ type: "text", text: "❌ ref と index は同時に指定できません。" }], isError: true };
+                }
+
+                // ref 解決 + revision チェック
+                const resolved = await resolveRefsAndCheckRevision({
+                    snapshotId: args?.snapshotId, ref: args?.ref,
+                    expectedRevision: args?.expectedRevision,
+                    mode, client, postId, sessionId: _sessionId, siteName: _siteName,
+                });
+                if (resolved.error) return resolved.error;
+                const _preState = resolved.currentState || null;  // Phase 2: 差分計算用
+
+                const index = resolved.index !== undefined ? resolved.index : args?.index;
+                if (index === undefined) {
+                    return { content: [{ type: "text", text: "❌ table_operations では index または ref のいずれかが必要です。" }], isError: true };
+                }
+
                 const tableParams = {
                     index, action,
                     row: args.row, col: args.col,
@@ -2557,16 +4228,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return text;
                 };
 
+                const _isWrite = action !== 'get_structure';
                 const _mt_to = process.env.FRIDAY_DEBUG === '1' ? `\n[DEBUG] mode=${mode}` : '';
                 if (mode === 'headless') {
                     const _guard = await guardHeadlessConflict(postId, client, name);
                     if (_guard) return _guard;
                     try {
                         const result = await client.headlessTableOperation(postId, tableParams);
-                        if (action === 'get_structure') {
+                        if (!_isWrite) {
                             return { content: [{ type: "text", text: formatStructure(result) + _mt_to }] };
                         }
-                        return { content: [{ type: "text", text: `✅ ${action} 完了: ${JSON.stringify(result.detail || result)}${_mt_to}` }] };
+                        const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                        const _msg = `✅ ${action} 完了: ${JSON.stringify(result.detail || result)}${_mt_to}`;
+                        if (_inputRef) {
+                            const changedIndex = result.targetIndex ?? index;
+                            const syntheticResult = { changes: [{ oldIndex: changedIndex, newIndices: [changedIndex], success: true }] };
+                            const changeInfo = buildChangeInfoFromResult('updated', _snap, syntheticResult, _preState);
+                            if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                        }
+                        return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -2581,10 +4261,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!result.success)
                     return errorResponse(name, result.error, args?.site);
 
-                if (action === 'get_structure') {
+                if (!_isWrite) {
                     return { content: [{ type: "text", text: formatStructure(result.structure) + _mt_to }] };
                 }
-                return { content: [{ type: "text", text: `✅ ${action} 完了: ${JSON.stringify(result.detail || {})}${_mt_to}` }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName, result);
+                const _msg = `✅ ${action} 完了: ${JSON.stringify(result.detail || {})}${_mt_to}`;
+                if (_inputRef) {
+                    const changedIndex = result.targetIndex ?? index;
+                    const syntheticResult = { changes: [{ oldIndex: changedIndex, newIndices: [changedIndex], success: true }] };
+                    const changeInfo = buildChangeInfoFromResult('updated', _snap, syntheticResult, _preState);
+                    if (changeInfo) return { content: [{ type: "text", text: appendRefChangesToText(_msg, changeInfo) }] };
+                }
+                return { content: [{ type: "text", text: appendSnapshotToTextLegacy(_msg, _snap) }] };
             }
 
             case "open_in_browser": {