friday-mcp-v2 3.0.0 → 3.0.1

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,205 @@ 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 を返して再取得の往復を省く
+    const latestSnapshot = buildSnapshotFromState(currentState, mode, postId, sessionId, siteName);
+    let text = `❌ REVISION_MISMATCH: 記事の構造が変更されています（expected: ${expectedRevision}, current: ${currentRevision}）。\n` +
+               `更新はスキップしました。以下の最新 snapshot で再試行してください。`;
+    if (latestSnapshot) {
+        text = appendSnapshotToText(text, latestSnapshot);
+    }
+    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 +736,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 +783,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 +841,448 @@ 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 };
+            }
+            if (refs) {
+                const indices = refs.map(r => resolveRefFromState(snapshotId, r, mode, sessionId, postId, currentState));
+                return { indices };
+            }
+        } catch (e) {
+            return { error: {
+                content: [{ type: "text", text: `❌ ref 解決エラー: ${e.message}` }],
+                isError: true,
+            }};
+        }
+    }
+
+    // Case 2: ref なし + expectedRevision のみ
+    if (expectedRevision) {
+        const { error } = await acquireFreshState({
+            expectedRevision, mode, client, postId, sessionId, siteName,
+        });
+        if (error) return { error };
+    }
+
+    // Case 3: どちらもなし
+    return {};
+}
+
+/**
+ * 更新後のレスポンス snapshot を構築する
+ * @param {string} mode
+ * @param {object} client
+ * @param {number} postId
+ * @param {string|null} sessionId
+ * @param {string} siteName
+ * @returns {Promise<object|null>} { snapshotId, revision, blocks[] } or null
+ */
+async function buildResponseSnapshot(mode, client, postId, sessionId, siteName) {
+    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,
+        })),
+    };
+}
+
+/**
+ * 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 appendSnapshotToText(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;
+}
+
+/**
+ * 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);
+    }
+
+    // 2. 降順ソート（index が大きい方から処理 — 1 op = 1 index なので安全）
+    resolvedOps.sort((a, b) => b.resolvedIndex - a.resolvedIndex);
+
+    // 3. 各 operation を順次実行
+    const results = [];
+    for (const op of resolvedOps) {
+        const index = op.resolvedIndex;
+
+        let opResult;
+        try {
+            // batch は ref → index 解決済み。1 op = 1 index で下流に渡す
+            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);
+            }
+
+            results.push({
+                ref: op.ref,
+                resolvedIndex: op.resolvedIndex,
+                status: (opResult && opResult.success !== false && opResult.ok !== false) ? 'updated' : 'failed',
+                error: opResult?.error || null,
+            });
+        } catch (e) {
+            results.push({
+                ref: op.ref,
+                resolvedIndex: op.resolvedIndex,
+                status: 'failed',
+                error: e.message,
+            });
+        }
+    }
+
+    // 4. レスポンス snapshot 構築
+    const snapshot = await buildResponseSnapshot(mode, client, postId, sessionId, siteName);
+
+    // レスポンス組み立て
+    // 注: 1→N 展開の newRefs[] は snapshot.blocks[] 全体を返しているため、
+    //      AI は新 snapshot から直接新しい ref を特定できる。
+    //      per-operation の newRefs 追跡は複数変更時に不正確になるため省略。
+    const successCount = results.filter(r => r.status !== 'failed').length;
+    const failCount = results.filter(r => r.status === 'failed').length;
+    let text = `✅ batch 完了\n\n成功: ${successCount} / 失敗: ${failCount}`;
+    for (const r of results) {
+        const refLabel = r.ref ? ` (${r.ref})` : '';
+        text += `\n  [${r.resolvedIndex}]${refLabel}: ${r.status}`;
+        if (r.error) text += ` — ${r.error}`;
+    }
+    text = appendSnapshotToText(text + _modeTag, snapshot);
+
+    return { content: [{ type: "text", text }] };
+}
+
 // フィードバック送信ヘルパー
 const FEEDBACK_URL = process.env.FRIDAY_FEEDBACK_URL || '';
 async function sendFeedback(data) {
@@ -776,7 +1431,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 +1440,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 +1460,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 +1494,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 +1586,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 +1595,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 +1629,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 +1717,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 +1758,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 +1835,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 +1862,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 +1892,31 @@ 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;
+    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 +1924,11 @@ async function handleUpdateBlocksTool(args, toolName) {
             _fromInsertBlock, appendToEnd } = (args || {});
     let { newHTML } = (args || {});
 
+    // [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 +1969,7 @@ async function handleUpdateBlocksTool(args, toolName) {
         };
     }
 
-    // --- ターゲットチェック（appendToEnd 時は不要） ---
+    // --- ターゲットチェック（appendToEnd / _parentIndex 時は不要） ---
     const hasTarget = target || index !== undefined || indices ||
         startIndex !== undefined || section || blockType || contains ||
         (headingLevel && headingContains);
@@ -1238,7 +2011,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);
+                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
             }
 
             const result = await client.headlessUpdate(postId, {
@@ -1263,13 +2037,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);
             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: appendSnapshotToText(`✅ 完了\n\n成功: ${successCount} / 失敗: ${failCount}${deprecationWarning}`, _snap, _refInfo) }] };
             }
 
-            return { content: [{ type: "text", text: `✅ 更新完了${deprecationWarning}${_modeTag}` }] };
+            return { content: [{ type: "text", text: appendSnapshotToText(`✅ 更新完了${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
         } catch (e) {
             const formatted = formatHeadlessConflictError(e);
             if (formatted) return formatted;
@@ -1291,7 +2066,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);
+        return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${count}ブロック挿入 at end${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
     }
 
     // target: "selected" の場合 → エディタ状態から選択情報を取得してMCP側で処理
@@ -1344,7 +2120,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);
+                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${hasTextSelection ? "（カーソル選択モード）" : "（差分）"}${deprecationWarning}`, _snap, _refInfo) }] };
+            }
         }
 
         // newHTMLの場合
@@ -1360,7 +2139,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);
+                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}`, _snap, _refInfo) }] };
+            }
         }
 
         // attributeUpdatesの場合
@@ -1374,12 +2156,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);
+            return { content: [{ type: "text", text: appendSnapshotToText(`✅ 属性更新完了${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 +2173,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 +2198,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);
     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: appendSnapshotToText(`✅ 完了\n\n成功: ${successCount} / スキップ: ${skipCount} / 失敗: ${failCount}\n\n${detailText}${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
     }
 
-    return { content: [{ type: "text", text: `✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}${_modeTag}` }] };
+    return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.mode === "insert" ? "挿入" : "更新"}完了${deprecationWarning}${_modeTag}`, _snap, _refInfo) }] };
 }
 
 // ツール実行のハンドラ
@@ -1475,6 +2262,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 +2332,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 +2347,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 +2384,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 +2403,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 +2415,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 +2445,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 +2457,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 +2531,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 +2559,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 +2624,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 +2636,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 +2655,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 +2673,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 +2735,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 +2744,29 @@ 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;
+
+                let { index, count, indices } = args;
+                if (resolved.index !== undefined) { index = resolved.index; count = count || 1; }
+                if (resolved.indices !== undefined) { indices = resolved.indices; }
 
                 // indices と index/count の排他バリデーション
                 if (indices !== undefined && (index !== undefined || count !== undefined)) {
@@ -1953,7 +2788,8 @@ 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);
+                            return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`, _snap) }] };
                         } catch (e) {
                             const formatted = formatHeadlessConflictError(e);
                             if (formatted) return formatted;
@@ -1967,7 +2803,8 @@ 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);
+                    return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`, _snap) }] };
                 }
 
                 // 既存モード（index + count）
@@ -1978,7 +2815,8 @@ 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);
+                        return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -1992,11 +2830,12 @@ 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);
+                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${result.count}ブロック削除\n\n${details}${_mt_db}`, _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 +2844,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,14 +2860,63 @@ 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 };
                 }
-                if (!hasTopLevel && !hasFlat) {
-                    return { content: [{ type: "text", text: "❌ from/to または fromFlat/toFlat を指定してください。" }], isError: true };
+
+                // expectedRevision チェック（全モード共通）
+                // ref モード以外でも expectedRevision が指定されていれば revision チェックを実施
+                if (args?.expectedRevision && !hasRef) {
+                    const { error: _revError } = await acquireFreshState({
+                        expectedRevision: args.expectedRevision,
+                        mode, client, postId, sessionId: _sessionId, siteName: _siteName,
+                    });
+                    if (_revError) return _revError;
+                }
+
+                // 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;
+
+                    // 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 モードに合流
                 }
 
                 // 移動結果のレスポンス生成ヘルパー
@@ -2039,8 +2929,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 +2941,8 @@ 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);
+                            return { content: [{ type: "text", text: appendSnapshotToText(moveMsg(result.moved), _snap) }] };
                         } catch (e) {
                             const formatted = formatHeadlessConflictError(e);
                             if (formatted) return formatted;
@@ -2064,7 +2955,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);
+                    return { content: [{ type: "text", text: appendSnapshotToText(moveMsg(result.moved), _snap) }] };
                 }
 
                 // 既存モード（from/to トップレベル）
@@ -2075,7 +2967,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);
+                        return { content: [{ type: "text", text: appendSnapshotToText(moveMsg(result.moved), _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -2088,7 +2981,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);
+                return { content: [{ type: "text", text: appendSnapshotToText(moveMsg(result.moved), _snap) }] };
             }
 
             case "undo": {
@@ -2124,7 +3018,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 +3027,22 @@ 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 };
+                }
+
+                // 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 { index } = args;
+                const index = resolved.index !== undefined ? resolved.index : args?.index;
 
                 if (mode === 'headless') {
                     const _guard = await guardHeadlessConflict(postId, client, name);
@@ -2144,7 +3052,8 @@ 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);
+                        return { content: [{ type: "text", text: appendSnapshotToText(`✅ ブロック複製完了 (index ${result.duplicated.index} → ${result.duplicated.newIndex})${_mt_dup}`, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -2157,7 +3066,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: `✅ ブロック複製完了${_mt_dup}` }] };
+                const _snap = await buildResponseSnapshot(mode, client, postId, _sessionId, _siteName);
+                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ブロック複製完了${_mt_dup}`, _snap) }] };
             }
 
             case "save_post": {
@@ -2362,13 +3272,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 +3313,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);
             }
 
@@ -2510,7 +3463,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 +3471,31 @@ 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 || {});
                 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 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 +3526,18 @@ 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);
+                        return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${action} 完了: ${JSON.stringify(result.detail || result)}${_mt_to}`, _snap) }] };
                     } catch (e) {
                         const formatted = formatHeadlessConflictError(e);
                         if (formatted) return formatted;
@@ -2581,10 +3552,11 @@ 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);
+                return { content: [{ type: "text", text: appendSnapshotToText(`✅ ${action} 完了: ${JSON.stringify(result.detail || {})}${_mt_to}`, _snap) }] };
             }
 
             case "open_in_browser": {