From 678901022b61db77cb12517fa6c0754bfdb91b18 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 20 May 2026 10:56:53 +0000 Subject: [PATCH 01/44] =?UTF-8?q?feat(editor):=20=E3=83=9A=E3=83=BC?= =?UTF-8?q?=E3=82=B8=E3=82=A2=E3=82=AF=E3=82=B7=E3=83=A7=E3=83=B3=E3=83=A1?= =?UTF-8?q?=E3=83=8B=E3=83=A5=E3=83=BC=E3=81=AB=E3=80=8CPDF=E3=81=A7?= =?UTF-8?q?=E5=87=BA=E5=8A=9B=E3=80=8D=E3=82=92=E8=BF=BD=E5=8A=A0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `PageEditorHeader` のアクションメニューに、Markdown エクスポートと同じ UX で PDF を直接ダウンロードする項目を追加する。クライアント側で Tiptap JSON を HTML 化し、html2pdf.js (html2canvas + jsPDF) で書き出すことで、新規サーバー エンドポイントを追加せずに済むようにした。 - `src/lib/tiptapToHtml.ts`: Tiptap JSON → 印刷向け HTML 変換と `downloadPdf` - `src/components/editor/PageEditor/usePdfExport.ts`: トースト付きハンドラ - `NotePageView` の編集可/読み取り専用ビュー両方にメニュー項目を統合 - ja/en の i18n キー (`editor.pageMenu.exportPdf`, `editor.pdfExport.*`) - 単体テスト (tiptapToHtml: 13, usePdfExport: 3, NotePageView: 30 件) Add an "Export as PDF" action to the page editor's overflow menu, mirroring the Markdown export UX with a direct download. Client-side conversion via `html2pdf.js` keeps the new feature off the server. Wired into both editable and read-only views; the read-only path disables the item until `usePagePublicContent` resolves, matching the Markdown export gating. --- bun.lock | 45 +++ package.json | 1 + .../editor/PageEditor/usePdfExport.test.tsx | 96 +++++ .../editor/PageEditor/usePdfExport.ts | 48 +++ src/i18n/locales/en/editor.json | 6 + src/i18n/locales/ja/editor.json | 6 + src/lib/markdownExport.ts | 9 +- src/lib/tiptapToHtml.test.ts | 243 +++++++++++++ src/lib/tiptapToHtml.ts | 330 ++++++++++++++++++ src/pages/NotePageView.test.tsx | 25 +- src/pages/NotePageView.tsx | 29 +- 11 files changed, 833 insertions(+), 5 deletions(-) create mode 100644 src/components/editor/PageEditor/usePdfExport.test.tsx create mode 100644 src/components/editor/PageEditor/usePdfExport.ts create mode 100644 src/lib/tiptapToHtml.test.ts create mode 100644 src/lib/tiptapToHtml.ts diff --git a/bun.lock b/bun.lock index 5ad7318c..4a03b0bd 100644 --- a/bun.lock +++ b/bun.lock @@ -88,6 +88,7 @@ "dompurify": "^3.3.3", "embla-carousel-react": "^8.6.0", "highlight.js": "^11.11.1", + "html2pdf.js": "^0.14.0", "i18next": "^26.0.1", "i18next-browser-languagedetector": "^8.2.1", "idb-keyval": "^6.2.2", @@ -1425,8 +1426,12 @@ "@types/node": ["@types/node@25.3.5", "", { "dependencies": { "undici-types": "~7.18.0" } }, "sha512-oX8xrhvpiyRCQkG1MFchB09f+cXftgIXb3a7UUa4Y3wpmZPw5tyZGTLWhlESOLq1Rq6oDlc8npVU2/9xiCuXMA=="], + "@types/pako": ["@types/pako@2.0.4", "", {}, "sha512-VWDCbrLeVXJM9fihYodcLiIv0ku+AlOa/TQ1SvYOaBuyrSKgEcro95LJyIsJ4vSo6BXIxOKxiJAat04CmST9Fw=="], + "@types/pg": ["@types/pg@8.18.0", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-gT+oueVQkqnj6ajGJXblFR4iavIXWsGAFCk3dP4Kki5+a9R4NMt0JARdk6s8cUKcfUoqP5dAtDSLU8xYUTFV+Q=="], + "@types/raf": ["@types/raf@3.4.3", "", {}, "sha512-c4YAvMedbPZ5tEyxzQdMoOhhJ4RD3rngZIdwC2/qDN3d7JpEhB6fiBRKVY1lg5B7Wk+uPBjn5f39j1/2MY1oOw=="], + "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="], "@types/react-dom": ["@types/react-dom@19.2.3", "", { "peerDependencies": { "@types/react": "^19.2.0" } }, "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ=="], @@ -1559,6 +1564,8 @@ "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="], + "base64-arraybuffer": ["base64-arraybuffer@1.0.2", "", {}, "sha512-I3yl4r9QB5ZRY3XuJVEPfc2XhZO6YweFPI+UovAzn+8/hb3oJ6lnysaFcjVpkCPfVWFUDvoZ8kmVDP7WyRtYtQ=="], + "base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="], "baseline-browser-mapping": ["baseline-browser-mapping@2.9.19", "", { "bin": { "baseline-browser-mapping": "dist/cli.js" } }, "sha512-ipDqC8FrAl/76p2SSWKSI+H9tFwm7vYqXQrItCuiVPt26Km0jS+NzSsBWAaBusvSbQcfJG+JitdMm+wZAgTYqg=="], @@ -1605,6 +1612,8 @@ "caniuse-lite": ["caniuse-lite@1.0.30001769", "", {}, "sha512-BCfFL1sHijQlBGWBMuJyhZUhzo7wer5sVj9hqekB/7xn0Ypy+pER/edCYQm4exbXj4WiySGp40P8UuTh6w1srg=="], + "canvg": ["canvg@3.0.11", "", { "dependencies": { "@babel/runtime": "^7.12.5", "@types/raf": "^3.4.0", "core-js": "^3.8.3", "raf": "^3.4.1", "regenerator-runtime": "^0.13.7", "rgbcolor": "^1.0.1", "stackblur-canvas": "^2.0.0", "svg-pathdata": "^6.0.3" } }, "sha512-5ON+q7jCTgMp9cjpu4Jo6XbvfYwSB2Ow3kzHKfIyJfaCAOHLbdKPQqGKgfED/R5B+3TFFfe8pegYA+b423SRyA=="], + "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="], "chai": ["chai@6.2.2", "", {}, "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg=="], @@ -1671,6 +1680,8 @@ "cookie-signature": ["cookie-signature@1.2.2", "", {}, "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg=="], + "core-js": ["core-js@3.49.0", "", {}, "sha512-es1U2+YTtzpwkxVLwAFdSpaIMyQaq0PBgm3YD1W3Qpsn1NAmO3KSgZfu+oGSWVu6NvLHoHCV/aYcsE5wiB7ALg=="], + "cors": ["cors@2.8.6", "", { "dependencies": { "object-assign": "^4", "vary": "^1" } }, "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw=="], "cose-base": ["cose-base@1.0.3", "", { "dependencies": { "layout-base": "^1.0.0" } }, "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg=="], @@ -1687,6 +1698,8 @@ "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="], + "css-line-break": ["css-line-break@2.1.0", "", { "dependencies": { "utrie": "^1.0.2" } }, "sha512-FHcKFCZcAha3LwfVBhCQbW2nCNbkZXn7KVUJcsT5/P8YmfsVja0FMPJr0B903j/E69HUphKiV9iQArX8SDYA4w=="], + "css-tree": ["css-tree@3.2.1", "", { "dependencies": { "mdn-data": "2.27.1", "source-map-js": "^1.2.1" } }, "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA=="], "css.escape": ["css.escape@1.5.1", "", {}, "sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg=="], @@ -1949,6 +1962,8 @@ "fast-levenshtein": ["fast-levenshtein@2.0.6", "", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="], + "fast-png": ["fast-png@6.4.0", "", { "dependencies": { "@types/pako": "^2.0.3", "iobuffer": "^5.3.2", "pako": "^2.1.0" } }, "sha512-kAqZq1TlgBjZcLr5mcN6NP5Rv4V2f22z00c3g8vRrwkcqjerx7BEhPbOnWCPqaHUl2XWQBJQvOT/FQhdMT7X/Q=="], + "fast-sha256": ["fast-sha256@1.3.0", "", {}, "sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ=="], "fast-string-truncated-width": ["fast-string-truncated-width@3.0.3", "", {}, "sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g=="], @@ -1967,6 +1982,8 @@ "fetch-blob": ["fetch-blob@3.2.0", "", { "dependencies": { "node-domexception": "^1.0.0", "web-streams-polyfill": "^3.0.3" } }, "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ=="], + "fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="], + "figures": ["figures@6.1.0", "", { "dependencies": { "is-unicode-supported": "^2.0.0" } }, "sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg=="], "file-entry-cache": ["file-entry-cache@8.0.0", "", { "dependencies": { "flat-cache": "^4.0.0" } }, "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ=="], @@ -2093,6 +2110,10 @@ "html-url-attributes": ["html-url-attributes@3.0.1", "", {}, "sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ=="], + "html2canvas": ["html2canvas@1.4.1", "", { "dependencies": { "css-line-break": "^2.1.0", "text-segmentation": "^1.0.3" } }, "sha512-fPU6BHNpsyIhr8yyMpTLLxAbkaK8ArIBcmZIRiBLiDhjeqvXolaEmDGmELFuX9I4xDcaKKcJl+TKZLqruBbmWA=="], + + "html2pdf.js": ["html2pdf.js@0.14.0", "", { "dependencies": { "dompurify": "^3.3.1", "html2canvas": "^1.0.0", "jspdf": "^4.0.0" } }, "sha512-yvNJgE/8yru2UeGflkPdjW8YEY+nDH5X7/2WG4uiuSCwYiCp8PZ8EKNiTAa6HxJ1NjC51fZSIEq6xld5CADKBQ=="], + "http-errors": ["http-errors@2.0.1", "", { "dependencies": { "depd": "~2.0.0", "inherits": "~2.0.4", "setprototypeof": "~1.2.0", "statuses": "~2.0.2", "toidentifier": "~1.0.1" } }, "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ=="], "https-proxy-agent": ["https-proxy-agent@7.0.6", "", { "dependencies": { "agent-base": "^7.1.2", "debug": "4" } }, "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw=="], @@ -2131,6 +2152,8 @@ "internmap": ["internmap@2.0.3", "", {}, "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg=="], + "iobuffer": ["iobuffer@5.4.0", "", {}, "sha512-DRebOWuqDvxunfkNJAlc3IzWIPD5xVxwUNbHr7xKB8E6aLJxIPfNX3CoMJghcFjpv6RWQsrcJbghtEwSPoJqMA=="], + "ip-address": ["ip-address@10.1.0", "", {}, "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q=="], "ipaddr.js": ["ipaddr.js@1.9.1", "", {}, "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g=="], @@ -2267,6 +2290,8 @@ "json5": ["json5@2.2.3", "", { "bin": { "json5": "lib/cli.js" } }, "sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg=="], + "jspdf": ["jspdf@4.2.1", "", { "dependencies": { "@babel/runtime": "^7.28.6", "fast-png": "^6.2.0", "fflate": "^0.8.1" }, "optionalDependencies": { "canvg": "^3.0.11", "core-js": "^3.6.0", "dompurify": "^3.3.1", "html2canvas": "^1.0.0-rc.5" } }, "sha512-YyAXyvnmjTbR4bHQRLzex3CuINCDlQnBqoSYyjJwTP2x9jDLuKDzy7aKUl0hgx3uhcl7xzg32agn5vlie6HIlQ=="], + "jsx-ast-utils": ["jsx-ast-utils@3.3.5", "", { "dependencies": { "array-includes": "^3.1.6", "array.prototype.flat": "^1.3.1", "object.assign": "^4.1.4", "object.values": "^1.1.6" } }, "sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ=="], "jwa": ["jwa@2.0.1", "", { "dependencies": { "buffer-equal-constant-time": "^1.0.1", "ecdsa-sig-formatter": "1.0.11", "safe-buffer": "^5.0.1" } }, "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg=="], @@ -2573,6 +2598,8 @@ "package-manager-detector": ["package-manager-detector@1.6.0", "", {}, "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA=="], + "pako": ["pako@2.1.0", "", {}, "sha512-w+eufiZ1WuJYgPXbV/PO3NCMEc3xqylkKHzp8bxp1uW4qaSNQUkwmLLEc3kKsfz8lpV1F8Ht3U1Cm+9Srog2ug=="], + "parent-module": ["parent-module@1.0.1", "", { "dependencies": { "callsites": "^3.0.0" } }, "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g=="], "parse-entities": ["parse-entities@4.0.2", "", { "dependencies": { "@types/unist": "^2.0.0", "character-entities-legacy": "^3.0.0", "character-reference-invalid": "^2.0.0", "decode-named-character-reference": "^1.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0", "is-hexadecimal": "^2.0.0" } }, "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw=="], @@ -2605,6 +2632,8 @@ "pdfjs-dist": ["pdfjs-dist@5.7.284", "", { "optionalDependencies": { "@napi-rs/canvas": "^0.1.100" } }, "sha512-h4EdYQczmGhbOlqc3PPZwxevn7ApdWPbovAuWXOB/DjIyigSnwfy2oze7c6mRcSr9XgLp3eN3EeL4DyySTPMFw=="], + "performance-now": ["performance-now@2.1.0", "", {}, "sha512-7EAHlyLHI56VEIdK57uwHdHKIaAGbnXPiw0yWbarQZOKaKpvUIgW0jWRVLiatnM+XXlSwsanIBH/hzGMJulMow=="], + "pg": ["pg@8.19.0", "", { "dependencies": { "pg-connection-string": "^2.11.0", "pg-pool": "^3.12.0", "pg-protocol": "^1.12.0", "pg-types": "2.2.0", "pgpass": "1.0.5" }, "optionalDependencies": { "pg-cloudflare": "^1.3.0" }, "peerDependencies": { "pg-native": ">=3.0.1" }, "optionalPeers": ["pg-native"] }, "sha512-QIcLGi508BAHkQ3pJNptsFz5WQMlpGbuBGBaIaXsWK8mel2kQ/rThYI+DbgjUvZrIr7MiuEuc9LcChJoEZK1xQ=="], "pg-cloudflare": ["pg-cloudflare@1.3.0", "", {}, "sha512-6lswVVSztmHiRtD6I8hw4qP/nDm1EJbKMRhf3HCYaqud7frGysPv7FYJ5noZQdhQtN2xJnimfMtvQq21pdbzyQ=="], @@ -2731,6 +2760,8 @@ "queue-microtask": ["queue-microtask@1.2.3", "", {}, "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="], + "raf": ["raf@3.4.1", "", { "dependencies": { "performance-now": "^2.1.0" } }, "sha512-Sq4CW4QhwOHE8ucn6J34MqtZCeWFP2aQSmrlroYgqAV1PjStIhJXxYuTgUIfkEk7zTLjmIjLmU5q+fbD1NnOJA=="], + "range-parser": ["range-parser@1.2.1", "", {}, "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg=="], "raw-body": ["raw-body@3.0.2", "", { "dependencies": { "bytes": "~3.1.2", "http-errors": "~2.0.1", "iconv-lite": "~0.7.0", "unpipe": "~1.0.0" } }, "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA=="], @@ -2807,6 +2838,8 @@ "reusify": ["reusify@1.0.4", "", {}, "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw=="], + "rgbcolor": ["rgbcolor@1.0.1", "", {}, "sha512-9aZLIrhRaD97sgVhtJOW6ckOEh6/GnvQtdVNfdZ6s67+3/XwLS9lBcQYzEEhYVeUowN7pRzMLsyGhK2i/xvWbw=="], + "rimraf": ["rimraf@5.0.10", "", { "dependencies": { "glob": "^10.3.7" }, "bin": { "rimraf": "dist/esm/bin.mjs" } }, "sha512-l0OE8wL34P4nJH/H2ffoaniAokM2qSmrtXHmlpvYr5AVVX8msAyW0l8NVJFDxlSK4u3Uh/f41cQheDVdnYijwQ=="], "robust-predicates": ["robust-predicates@3.0.2", "", {}, "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg=="], @@ -2901,6 +2934,8 @@ "stackback": ["stackback@0.0.2", "", {}, "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw=="], + "stackblur-canvas": ["stackblur-canvas@2.7.0", "", {}, "sha512-yf7OENo23AGJhBriGx0QivY5JP6Y1HbrrDI6WLt6C5auYZXlQrheoY8hD4ibekFKz1HOfE48Ww8kMWMnJD/zcQ=="], + "standardwebhooks": ["standardwebhooks@1.0.0", "", { "dependencies": { "@stablelib/base64": "^1.0.0", "fast-sha256": "^1.3.0" } }, "sha512-BbHGOQK9olHPMvQNHWul6MYlrRTAOKn03rOe4A8O3CLWhNf4YHBqq2HJKKC+sfqpxiBY52pNeesD6jIiLDz8jg=="], "statuses": ["statuses@2.0.2", "", {}, "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw=="], @@ -2947,6 +2982,8 @@ "supports-preserve-symlinks-flag": ["supports-preserve-symlinks-flag@1.0.0", "", {}, "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w=="], + "svg-pathdata": ["svg-pathdata@6.0.3", "", {}, "sha512-qsjeeq5YjBZ5eMdFuUa4ZosMLxgr5RZ+F+Y1OrDhuOCEInRMA3x74XdBtggJcj9kOeInz0WE+LgCPDkZFlBYJw=="], + "symbol-tree": ["symbol-tree@3.2.4", "", {}, "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw=="], "tailwind-merge": ["tailwind-merge@3.5.0", "", {}, "sha512-I8K9wewnVDkL1NTGoqWmVEIlUcB9gFriAEkXkfCjX5ib8ezGxtR3xD7iZIxrfArjEsH7F1CHD4RFUtxefdqV/A=="], @@ -2961,6 +2998,8 @@ "tesseract.js-core": ["tesseract.js-core@7.0.0", "", {}, "sha512-WnNH518NzmbSq9zgTPeoF8c+xmilS8rFIl1YKbk/ptuuc7p6cLNELNuPAzcmsYw450ca6bLa8j3t0VAtq435Vw=="], + "text-segmentation": ["text-segmentation@1.0.3", "", { "dependencies": { "utrie": "^1.0.2" } }, "sha512-iOiPUo/BGnZ6+54OsWxZidGCsdU8YbE4PSpdPinp7DeMtUJNJBoJ/ouUSTJjHkh1KntHaltHl/gDs2FC4i5+Nw=="], + "thenify": ["thenify@3.3.1", "", { "dependencies": { "any-promise": "^1.0.0" } }, "sha512-RVZSIV5IG10Hk3enotrhvz0T9em6cyHBLkH/YAZuKqd8hRkKhSfCGIcP2KUY0EPxndzANBmNllzWPwak+bheSw=="], "thenify-all": ["thenify-all@1.6.0", "", { "dependencies": { "thenify": ">= 3.1.0 < 4" } }, "sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA=="], @@ -3075,6 +3114,8 @@ "util-deprecate": ["util-deprecate@1.0.2", "", {}, "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw=="], + "utrie": ["utrie@1.0.2", "", { "dependencies": { "base64-arraybuffer": "^1.0.2" } }, "sha512-1MLa5ouZiOmQzUbjbu9VmjLzn1QLXBhwpUa7kdLUQK+KQ5KA9I1vk5U4YHe/X2Ch7PYnJfWuWT+VbuxbGwljhw=="], + "uuid": ["uuid@14.0.0", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-Qo+uWgilfSmAhXCMav1uYFynlQO7fMFiMVZsQqZRMIXp0O7rR7qjkj+cPvBHLgBqi960QCoo/PH2/6ZtVqKvrg=="], "vary": ["vary@1.1.2", "", {}, "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg=="], @@ -3403,6 +3444,8 @@ "bun-types/@types/node": ["@types/node@22.16.5", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-bJFoMATwIGaxxx8VJPeM8TonI8t579oRvgAuT8zFugJsJZgzqv0Fu8Mhp68iecjzG7cnN3mO2dJQ5uUM2EFrgQ=="], + "canvg/@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="], + "chokidar/glob-parent": ["glob-parent@5.1.2", "", { "dependencies": { "is-glob": "^4.0.1" } }, "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow=="], "cmdk/@radix-ui/react-dialog": ["@radix-ui/react-dialog@1.1.14", "", { "dependencies": { "@radix-ui/primitive": "1.1.2", "@radix-ui/react-compose-refs": "1.1.2", "@radix-ui/react-context": "1.1.2", "@radix-ui/react-dismissable-layer": "1.1.10", "@radix-ui/react-focus-guards": "1.1.2", "@radix-ui/react-focus-scope": "1.1.7", "@radix-ui/react-id": "1.1.1", "@radix-ui/react-portal": "1.1.9", "@radix-ui/react-presence": "1.1.4", "@radix-ui/react-primitive": "2.1.3", "@radix-ui/react-slot": "1.2.3", "@radix-ui/react-use-controllable-state": "1.2.2", "aria-hidden": "^1.2.4", "react-remove-scroll": "^2.6.3" }, "peerDependencies": { "@types/react": "*", "@types/react-dom": "*", "react": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc", "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc" } }, "sha512-+CpweKjqpzTmwRwcYECQcNYbI8V9VSQt0SNFKeEBLgfucbsLssU6Ppq7wUdNXEGb573bMjFhVjKVll8rmV6zMw=="], @@ -3463,6 +3506,8 @@ "jsdom/whatwg-mimetype": ["whatwg-mimetype@5.0.0", "", {}, "sha512-sXcNcHOC51uPGF0P/D4NVtrkjSU2fNsm9iog4ZvZJsL3rjoDAzXZhkm2MWt1y+PUdggKAYVoMAIYcs78wJ51Cw=="], + "jspdf/@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="], + "katex/commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="], "knip/jiti": ["jiti@2.6.1", "", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="], diff --git a/package.json b/package.json index 391d296c..54d429d9 100644 --- a/package.json +++ b/package.json @@ -173,6 +173,7 @@ "dompurify": "^3.3.3", "embla-carousel-react": "^8.6.0", "highlight.js": "^11.11.1", + "html2pdf.js": "^0.14.0", "i18next": "^26.0.1", "i18next-browser-languagedetector": "^8.2.1", "idb-keyval": "^6.2.2", diff --git a/src/components/editor/PageEditor/usePdfExport.test.tsx b/src/components/editor/PageEditor/usePdfExport.test.tsx new file mode 100644 index 00000000..49859138 --- /dev/null +++ b/src/components/editor/PageEditor/usePdfExport.test.tsx @@ -0,0 +1,96 @@ +import { describe, it, expect, vi, beforeEach } from "vitest"; +import { render, screen, fireEvent, waitFor } from "@testing-library/react"; + +const { mockDownloadPdf, mockToast } = vi.hoisted(() => ({ + mockDownloadPdf: vi.fn(), + mockToast: vi.fn(), +})); + +vi.mock("@/lib/tiptapToHtml", () => ({ + downloadPdf: (...args: unknown[]) => mockDownloadPdf(...args), +})); + +vi.mock("@zedi/ui", () => ({ + useToast: () => ({ toast: mockToast }), +})); + +vi.mock("react-i18next", () => ({ + useTranslation: () => ({ + t: (key: string, fallback?: string) => { + if (typeof fallback === "string") return fallback; + return key; + }, + }), +})); + +import { usePdfExport } from "./usePdfExport"; + +function HookHarness({ + title, + content, + sourceUrl, +}: { + title: string; + content: string; + sourceUrl?: string | null; +}) { + const { handleExportPdf } = usePdfExport(title, content, sourceUrl ?? null); + return ( + + ); +} + +describe("usePdfExport", () => { + beforeEach(() => { + mockDownloadPdf.mockReset(); + mockToast.mockReset(); + }); + + it("delegates to downloadPdf with title / content / sourceUrl and i18n options", async () => { + mockDownloadPdf.mockResolvedValueOnce(undefined); + render(); + + fireEvent.click(screen.getByText("export")); + + await waitFor(() => { + expect(mockDownloadPdf).toHaveBeenCalledTimes(1); + }); + const [title, content, sourceUrl, options] = mockDownloadPdf.mock.calls[0] ?? []; + expect(title).toBe("My Page"); + expect(content).toBe("{}"); + expect(sourceUrl).toBe("https://example.com/article"); + expect(options).toMatchObject({ + defaultTitle: "notes.untitledPage", + attributionLabel: "editor.pdfExport.sourceAttribution", + }); + }); + + it("fires the success toast after downloadPdf resolves", async () => { + mockDownloadPdf.mockResolvedValueOnce(undefined); + render(); + + fireEvent.click(screen.getByText("export")); + + await waitFor(() => { + expect(mockToast).toHaveBeenCalledWith({ + title: "editor.pdfExport.downloaded", + }); + }); + }); + + it("fires a destructive toast when downloadPdf rejects", async () => { + mockDownloadPdf.mockRejectedValueOnce(new Error("boom")); + render(); + + fireEvent.click(screen.getByText("export")); + + await waitFor(() => { + expect(mockToast).toHaveBeenCalledWith({ + title: "editor.pdfExport.failed", + variant: "destructive", + }); + }); + }); +}); diff --git a/src/components/editor/PageEditor/usePdfExport.ts b/src/components/editor/PageEditor/usePdfExport.ts new file mode 100644 index 00000000..257235c2 --- /dev/null +++ b/src/components/editor/PageEditor/usePdfExport.ts @@ -0,0 +1,48 @@ +import { useCallback } from "react"; +import { useTranslation } from "react-i18next"; +import { useToast } from "@zedi/ui"; +import { downloadPdf } from "@/lib/tiptapToHtml"; + +/** + * `usePdfExport` の戻り値。Markdown エクスポート系フックと同じ形でハンドラだけを返す。 + * Return type of {@link usePdfExport}. Matches the shape of the Markdown export + * hooks (handlers only) so menu wiring stays symmetric. + */ +interface UsePdfExportReturn { + handleExportPdf: () => Promise; +} + +/** + * ページエディタの「PDFで出力」アクションを駆動するフック。クライアント側で + * Tiptap JSON を HTML 化し、html2pdf.js で PDF をダウンロードする。成功 / + * 失敗時にはトーストを発火する。 + * + * Hook that drives the page editor's "Export PDF" action. Converts Tiptap + * JSON to HTML in the browser and triggers an html2pdf.js download. Emits a + * success or destructive toast depending on the outcome. + */ +export function usePdfExport( + title: string, + content: string, + sourceUrl?: string | null, +): UsePdfExportReturn { + const { t } = useTranslation(); + const { toast } = useToast(); + + const handleExportPdf = useCallback(async () => { + try { + await downloadPdf(title, content, sourceUrl, { + defaultTitle: t("notes.untitledPage"), + attributionLabel: t("editor.pdfExport.sourceAttribution"), + }); + toast({ title: t("editor.pdfExport.downloaded") }); + } catch { + toast({ + title: t("editor.pdfExport.failed"), + variant: "destructive", + }); + } + }, [title, content, sourceUrl, toast, t]); + + return { handleExportPdf }; +} diff --git a/src/i18n/locales/en/editor.json b/src/i18n/locales/en/editor.json index 632ea2a6..d7671250 100644 --- a/src/i18n/locales/en/editor.json +++ b/src/i18n/locales/en/editor.json @@ -6,6 +6,7 @@ "collaborationLoading": "Loading editor", "pageMenu": { "exportMarkdown": "Export Markdown", + "exportPdf": "Export as PDF", "copyMarkdown": "Copy Markdown", "deletePage": "Delete" }, @@ -317,5 +318,10 @@ "downloaded": "Markdown file downloaded", "copied": "Markdown copied to clipboard", "copyFailed": "Copy failed" + }, + "pdfExport": { + "sourceAttribution": "📎 Source", + "downloaded": "PDF downloaded", + "failed": "Failed to generate PDF" } } diff --git a/src/i18n/locales/ja/editor.json b/src/i18n/locales/ja/editor.json index 92af551b..772c57c7 100644 --- a/src/i18n/locales/ja/editor.json +++ b/src/i18n/locales/ja/editor.json @@ -6,6 +6,7 @@ "collaborationLoading": "エディタを読み込み中", "pageMenu": { "exportMarkdown": "Markdownでエクスポート", + "exportPdf": "PDFで出力", "copyMarkdown": "Markdownをコピー", "deletePage": "削除" }, @@ -317,5 +318,10 @@ "downloaded": "Markdownファイルをダウンロードしました", "copied": "Markdownをクリップボードにコピーしました", "copyFailed": "コピーに失敗しました" + }, + "pdfExport": { + "sourceAttribution": "📎 引用元", + "downloaded": "PDFをダウンロードしました", + "failed": "PDFの生成に失敗しました" } } diff --git a/src/lib/markdownExport.ts b/src/lib/markdownExport.ts index ce294a67..d2968dc3 100644 --- a/src/lib/markdownExport.ts +++ b/src/lib/markdownExport.ts @@ -239,10 +239,13 @@ export function downloadMarkdown( } /** - * Sanitize filename for safe file system usage + * ダウンロードファイル名で使えない文字を `_` に置換し、長さを 100 文字に制限する。 + * Markdown / PDF 等エクスポート系コード間で共有する純粋関数。 + * + * Replace characters that are invalid in filenames with `_` and clamp the + * length to 100 chars. Shared across export utilities (Markdown / PDF). */ -function sanitizeFilename(name: string): string { - // Remove or replace characters that are invalid in filenames +export function sanitizeFilename(name: string): string { return name .replace(/[<>:"/\\|?*]/g, "_") .replace(/\s+/g, "_") diff --git a/src/lib/tiptapToHtml.test.ts b/src/lib/tiptapToHtml.test.ts new file mode 100644 index 00000000..0f716311 --- /dev/null +++ b/src/lib/tiptapToHtml.test.ts @@ -0,0 +1,243 @@ +import { describe, it, expect } from "vitest"; +import { tiptapToHtml } from "./tiptapToHtml"; + +describe("tiptapToHtml", () => { + it("converts a paragraph node to a

block", () => { + const json = JSON.stringify({ + type: "doc", + content: [{ type: "paragraph", content: [{ type: "text", text: "Hello world" }] }], + }); + expect(tiptapToHtml(json)).toBe("

Hello world

"); + }); + + it("converts body headings (levels 2–5) to matching h2–h5 tags", () => { + const json = JSON.stringify({ + type: "doc", + content: [ + { type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "H2" }] }, + { type: "heading", attrs: { level: 3 }, content: [{ type: "text", text: "H3" }] }, + { type: "heading", attrs: { level: 4 }, content: [{ type: "text", text: "H4" }] }, + { type: "heading", attrs: { level: 5 }, content: [{ type: "text", text: "H5" }] }, + ], + }); + const html = tiptapToHtml(json); + expect(html).toContain("

H2

"); + expect(html).toContain("

H3

"); + expect(html).toContain("

H4

"); + expect(html).toContain("
H5
"); + }); + + // 旧データに残っている level 1 / 欠損 level は最小の本文見出し `h2` にフォールバックさせる。 + // Legacy heading nodes with level 1 (or a missing level attribute) fall back to `h2`. + it("falls back to

when heading level is missing or below 2", () => { + const json = JSON.stringify({ + type: "doc", + content: [ + { type: "heading", attrs: { level: 1 }, content: [{ type: "text", text: "Legacy" }] }, + { type: "heading", content: [{ type: "text", text: "NoLevel" }] }, + ], + }); + const html = tiptapToHtml(json); + expect(html).toContain("

Legacy

"); + expect(html).toContain("

NoLevel

"); + expect(html).not.toContain("

"); + }); + + it("converts bullet and ordered lists, including nested lists", () => { + const json = JSON.stringify({ + type: "doc", + content: [ + { + type: "bulletList", + content: [ + { + type: "listItem", + content: [ + { type: "paragraph", content: [{ type: "text", text: "A" }] }, + { + type: "bulletList", + content: [ + { + type: "listItem", + content: [{ type: "paragraph", content: [{ type: "text", text: "A-1" }] }], + }, + ], + }, + ], + }, + { + type: "listItem", + content: [{ type: "paragraph", content: [{ type: "text", text: "B" }] }], + }, + ], + }, + { + type: "orderedList", + content: [ + { + type: "listItem", + content: [{ type: "paragraph", content: [{ type: "text", text: "1st" }] }], + }, + ], + }, + ], + }); + const html = tiptapToHtml(json); + expect(html).toContain("
    "); + // ネストした `
      ` が外側の `
    • ` 内側に来ること。 + // The nested `
        ` appears inside the outer `
      • `. + expect(html).toMatch(/

      • A<\/p>

        • A-1<\/p><\/li><\/ul><\/li>/); + expect(html).toContain("

        • B

          • "); + expect(html).toContain("
            "); + expect(html).toContain("

          1. 1st

            2. "); + }); + + it("converts blockquote and horizontalRule", () => { + const json = JSON.stringify({ + type: "doc", + content: [ + { + type: "blockquote", + content: [{ type: "paragraph", content: [{ type: "text", text: "Quoted" }] }], + }, + { type: "horizontalRule" }, + ], + }); + const html = tiptapToHtml(json); + expect(html).toContain("
            "); + expect(html).toContain("Quoted"); + expect(html).toContain("
            "); + expect(html).toContain(" { + const json = JSON.stringify({ + type: "doc", + content: [ + { + type: "codeBlock", + attrs: { language: "ts" }, + content: [{ type: "text", text: "" }], + }, + ], + }); + const html = tiptapToHtml(json); + expect(html).toContain('
            ');
+    expect(html).toContain("<script>alert(1)</script>");
+    expect(html).not.toContain("");
+  });
+
+  it("applies bold, italic, strike, inline-code, and link marks", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "b", marks: [{ type: "bold" }] },
+            { type: "text", text: "i", marks: [{ type: "italic" }] },
+            { type: "text", text: "s", marks: [{ type: "strike" }] },
+            { type: "text", text: "c", marks: [{ type: "code" }] },
+            {
+              type: "text",
+              text: "link",
+              marks: [{ type: "link", attrs: { href: "https://example.com/" } }],
+            },
+          ],
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("b");
+    expect(html).toContain("i");
+    expect(html).toContain("s");
+    expect(html).toContain("c");
+    expect(html).toContain('link');
+  });
+
+  it("escapes HTML-special characters in text nodes and attributes", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [
+            { type: "text", text: "<>&\"'" },
+            {
+              type: "text",
+              text: "x",
+              marks: [{ type: "link", attrs: { href: 'javascript:alert("x")' } }],
+            },
+          ],
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("<>&"'");
+    // 不正 scheme は完全に除外し、空 href として描画する（XSS 防止）。
+    // Reject non-http(s) schemes outright; emit an empty href to neutralise XSS.
+    expect(html).not.toContain('href="javascript:');
+  });
+
+  it("renders images with src/alt/title attribute escaping", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "image",
+          attrs: {
+            src: "https://example.com/img.png",
+            alt: 'alt "quote"',
+            title: "t",
+          },
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain('src="https://example.com/img.png"');
+    expect(html).toContain('alt="alt "quote""');
+    expect(html).toContain('title="t<itle>"');
+  });
+
+  it("renders wikiLink as bracketed text (no anchor target)", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "wikiLink", attrs: { title: "Foo" } }],
+        },
+      ],
+    });
+    expect(tiptapToHtml(json)).toContain("[[Foo]]");
+  });
+
+  it("emits empty output for malformed youtubeEmbed and a safe anchor for valid id", () => {
+    const invalid = JSON.stringify({
+      type: "doc",
+      content: [{ type: "paragraph", content: [{ type: "youtubeEmbed", attrs: { videoId: "" } }] }],
+    });
+    expect(tiptapToHtml(invalid)).toBe("
            ");
+
+    const valid = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "paragraph",
+          content: [{ type: "youtubeEmbed", attrs: { videoId: "abcdefghijk" } }],
+        },
+      ],
+    });
+    expect(tiptapToHtml(valid)).toContain(
+      'YouTube',
+    );
+  });
+
+  it("returns plain-text fallback when content is not valid JSON", () => {
+    expect(tiptapToHtml("just text")).toContain("just text");
+  });
+
+  it("renders an empty string for empty input", () => {
+    expect(tiptapToHtml("")).toBe("");
+  });
+});
diff --git a/src/lib/tiptapToHtml.ts b/src/lib/tiptapToHtml.ts
new file mode 100644
index 00000000..ad51df64
--- /dev/null
+++ b/src/lib/tiptapToHtml.ts
@@ -0,0 +1,330 @@
+import { sanitizeFilename } from "./markdownExport";
+
+/**
+ * Tiptap JSON を HTML 文字列へ変換し、html2pdf.js による PDF 書き出しを行う。
+ * `markdownExport.ts` と同じノード dispatch 方式で実装し、エクスポート経路で
+ * 重い React Node View 拡張を読み込まずに済むようにしている。
+ *
+ * Convert Tiptap JSON into HTML and drive html2pdf.js for client-side PDF
+ * export. Mirrors the dispatch pattern in `markdownExport.ts` so the
+ * export path avoids pulling heavy React node-view extensions.
+ */
+
+interface TiptapNode {
+  type: string;
+  attrs?: Record;
+  content?: TiptapNode[];
+  text?: string;
+  marks?: TiptapMark[];
+}
+
+interface TiptapMark {
+  type: string;
+  attrs?: Record;
+}
+
+/**
+ * Tiptap JSON 文字列を export 用 HTML 文字列へ変換する。
+ * 入力が JSON でなければプレーンテキストとしてそのままエスケープして返す。
+ *
+ * Convert a Tiptap JSON string to an HTML string suitable for PDF export.
+ * Non-JSON inputs are returned as escaped plain text.
+ */
+export function tiptapToHtml(content: string): string {
+  if (!content) return "";
+
+  try {
+    const doc = JSON.parse(content) as TiptapNode;
+    return convertNode(doc);
+  } catch {
+    // JSON でない場合はプレーンテキストとして扱う。
+    // Treat non-JSON inputs as plain text (still escape HTML metacharacters).
+    return escapeHtml(content);
+  }
+}
+
+type NodeHandler = (node: TiptapNode) => string;
+
+const nodeHandlers: Record = {};
+
+function convertNode(node: TiptapNode): string {
+  if (!node) return "";
+  const handler = nodeHandlers[node.type];
+  return handler ? handler(node) : convertChildren(node);
+}
+
+function convertChildren(node: TiptapNode): string {
+  if (!node.content) return "";
+  return node.content.map(convertNode).join("");
+}
+
+Object.assign(nodeHandlers, {
+  doc: (n) => convertChildren(n),
+  paragraph: (n) => `
            ${convertChildren(n)}
            `,
+  heading: (n) => {
+    // 本文の見出しは body schema 上 h2–h5。`level` が欠落 / 1 以下の旧データは
+    // ページタイトル `h1` と衝突しないよう最小の本文見出し `h2` にフォールバック。
+    // Body headings span h2–h5; legacy `level: 1` / missing falls back to `h2`
+    // so it never collides with the page-title `h1`.
+    const rawLevel = n.attrs?.level;
+    const level = typeof rawLevel === "number" && rawLevel >= 2 && rawLevel <= 6 ? rawLevel : 2;
+    return `${convertChildren(n)}`;
+  },
+  bulletList: (n) => `
              ${convertListChildren(n)}
            `,
+  orderedList: (n) => `
              ${convertListChildren(n)}
            `,
+  listItem: (n) => `
          2. ${convertChildren(n)}
            3. `,
+  taskList: (n) => `
              ${convertChildren(n)}
            `,
+  taskItem: (n) => {
+    const checked = Boolean(n.attrs?.checked);
+    const box = ``;
+    return `
          3. ${box} ${convertChildren(n)}
            4. `;
+  },
+  blockquote: (n) => `
            ${convertChildren(n)}
            `,
+  codeBlock: (n) => {
+    const language = typeof n.attrs?.language === "string" ? n.attrs.language : "";
+    const codeText = collectPlainText(n);
+    const langAttr = language ? ` class="language-${escapeHtmlAttr(language)}"` : "";
+    return `
            ${escapeHtml(codeText)}
            `;
+  },
+  horizontalRule: () => "
            ",
+  hardBreak: () => "
            ",
+  text: (n) => applyMarks(escapeHtml(n.text || ""), n.marks || []),
+  wikiLink: (n) => {
+    const title = typeof n.attrs?.title === "string" ? n.attrs.title : "";
+    return `[[${escapeHtml(title)}]]`;
+  },
+  image: (n) => {
+    const src = typeof n.attrs?.src === "string" ? n.attrs.src : "";
+    const alt = typeof n.attrs?.alt === "string" ? n.attrs.alt : "";
+    const title = typeof n.attrs?.title === "string" ? n.attrs.title : "";
+    const safeSrc = sanitizeUrl(src);
+    if (!safeSrc) return "";
+    const attrs = [`src="${escapeHtmlAttr(safeSrc)}"`, `alt="${escapeHtmlAttr(alt)}"`];
+    if (title) attrs.push(`title="${escapeHtmlAttr(title)}"`);
+    return ``;
+  },
+  youtubeEmbed: (n) => {
+    const rawVideoId = n.attrs?.videoId;
+    const videoId = typeof rawVideoId === "string" ? rawVideoId.trim() : "";
+    // 異常な videoId をそのまま href に入れないよう厳格に検証する。
+    // Strictly validate videoId before composing the anchor href.
+    if (!/^[a-zA-Z0-9_-]{11}$/.test(videoId)) return "";
+    return `YouTube`;
+  },
+  link: (n) => convertChildren(n),
+  // 表組みのフィデリティは print 時に効くので最低限 HTML  に落とす。
+  // Render tables as real HTML tables so print layout stays usable.
+  table: (n) => `
            ${convertChildren(n)}
            `,
+  tableRow: (n) => `${convertChildren(n)}`,
+  tableCell: (n) => `${convertChildren(n)}`,
+  tableHeader: (n) => `${convertChildren(n)}`,
+} satisfies Record);
+
+function convertListChildren(node: TiptapNode): string {
+  if (!node.content) return "";
+  return node.content.map(convertNode).join("");
+}
+
+/**
+ * codeBlock のテキストノードはマークを無視して raw 文字列を集める。
+ * Collect raw text content of a node tree (used by codeBlock).
+ */
+function collectPlainText(node: TiptapNode): string {
+  if (node.type === "text") return node.text ?? "";
+  if (!node.content) return "";
+  return node.content.map(collectPlainText).join("");
+}
+
+function applyMarks(text: string, marks: TiptapMark[]): string {
+  if (!marks || marks.length === 0) return text;
+  let result = text;
+  for (const mark of marks) {
+    switch (mark.type) {
+      case "bold":
+        result = `${result}`;
+        break;
+      case "italic":
+        result = `${result}`;
+        break;
+      case "strike":
+        result = `${result}`;
+        break;
+      case "underline":
+        result = `${result}`;
+        break;
+      case "code":
+        result = `${result}`;
+        break;
+      case "link": {
+        const href = typeof mark.attrs?.href === "string" ? mark.attrs.href : "";
+        const safeHref = sanitizeUrl(href);
+        if (!safeHref) break;
+        result = `${result}`;
+        break;
+      }
+      // 他の mark（highlight / color など）は print 時の重要度が低いので無視する。
+      // Other marks (highlight / color etc.) are dropped for export simplicity.
+    }
+  }
+  return result;
+}
+
+const HTML_ESCAPES: Record = {
+  "&": "&",
+  "<": "<",
+  ">": ">",
+  '"': """,
+  "'": "'",
+};
+
+/** Escape text nodes for safe HTML body insertion. */
+function escapeHtml(input: string): string {
+  return input.replace(/[&<>"']/g, (c) => HTML_ESCAPES[c] ?? c);
+}
+
+/** Escape attribute values. Same set as body, but kept as a separate fn for clarity. */
+function escapeHtmlAttr(input: string): string {
+  return escapeHtml(input);
+}
+
+/**
+ * 安全な URL スキームだけを許可する。`javascript:` 等をはじいて XSS を防ぐ。
+ * Allow only safe URL schemes; strip `javascript:` and friends to prevent XSS.
+ */
+function sanitizeUrl(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return "";
+  if (/^(https?:|mailto:|tel:|\/|#)/i.test(trimmed)) return trimmed;
+  if (/^data:image\//i.test(trimmed)) return trimmed;
+  // 相対 URL（先頭が `./` or 英数字）は許可する。
+  // Allow relative URLs (starts with `./` or alphanumeric path).
+  if (/^(\.{0,2}\/|[a-zA-Z0-9_-]+(\/|$))/.test(trimmed)) return trimmed;
+  return "";
+}
+
+/**
+ * PDF エクスポートのオプション。
+ * Options for {@link downloadPdf}.
+ */
+export interface PdfExportOptions {
+  /** Default title when the page title is empty. */
+  defaultTitle?: string;
+  /** Label for the source-attribution block (e.g. "📎 引用元"). */
+  attributionLabel?: string;
+  /** Page format. Defaults to `"a4"`. */
+  format?: "a4" | "letter";
+}
+
+/**
+ * 引用元ブロックを HTML として組み立てる。`sourceUrl` が空のときは空文字列を返す。
+ * Build the source-attribution block. Returns "" when `sourceUrl` is empty.
+ */
+function buildSourceAttribution(sourceUrl?: string | null, attributionLabel?: string): string {
+  if (!sourceUrl?.trim()) return "";
+  const safeUrl = sanitizeUrl(sourceUrl.trim());
+  if (!safeUrl) return "";
+  const label = (attributionLabel?.trim() || "📎 Source") + ":";
+  return (
+    `
            ` +
+    `${escapeHtml(label)} ${escapeHtml(safeUrl)}` +
+    `
            `
+  );
+}
+
+/**
+ * オフスクリーン DOM に組み立てたエクスポート用ルート要素を返す。
+ * Compose the offscreen export root used as html2pdf.js source.
+ */
+function buildExportRoot(html: string): HTMLDivElement {
+  const root = document.createElement("div");
+  root.className = "zedi-pdf-root";
+  root.style.cssText = [
+    "position:fixed",
+    "left:-99999px",
+    "top:0",
+    // A4 width at ~96dpi (210mm ≈ 794px). html2canvas captures this width.
+    "width:794px",
+    "padding:0",
+    "background:#fff",
+    "color:#111",
+    "font-family:'Hiragino Kaku Gothic ProN','Hiragino Sans','Yu Gothic','Meiryo','Noto Sans JP',system-ui,-apple-system,sans-serif",
+    "font-size:14px",
+    "line-height:1.7",
+  ].join(";");
+  root.innerHTML = html;
+  return root;
+}
+
+/**
+ * `downloadPdf` の内部で `html2pdf.js` を遅延 import するための疎結合点。
+ * テストで `vi.mock("html2pdf.js")` 経由でモックしやすくしてある。
+ *
+ * Indirection so tests can `vi.mock("html2pdf.js")` and assert calls without
+ * pulling the real library (which depends on canvas / DOM features absent in
+ * jsdom).
+ */
+async function loadHtml2Pdf(): Promise {
+  const mod = await import("html2pdf.js");
+  return mod.default;
+}
+
+/**
+ * ページ本文を PDF として保存する。`tiptapToHtml` で組み立てた HTML を
+ * オフスクリーン要素に流し込み、`html2pdf.js`（html2canvas + jsPDF）で
+ * 直接ダウンロードを発火する。
+ *
+ * Save the page body as a PDF. Renders `tiptapToHtml` output into an
+ * offscreen element and pipes it through `html2pdf.js` (html2canvas + jsPDF).
+ */
+export async function downloadPdf(
+  title: string,
+  content: string,
+  sourceUrl?: string | null,
+  options?: PdfExportOptions,
+): Promise {
+  const { defaultTitle = "Untitled", attributionLabel, format = "a4" } = options ?? {};
+  const normalizedTitle = title.trim();
+  const bodyHtml = tiptapToHtml(content);
+  const attributionHtml = buildSourceAttribution(sourceUrl, attributionLabel);
+  const titleHtml = normalizedTitle
+    ? `
            ${escapeHtml(normalizedTitle)}
            `
+    : "";
+
+  // 上下左右の余白は CSS padding に寄せず、jsPDF の `margin` で管理する。
+  // Manage margins via jsPDF options rather than CSS to keep page breaks predictable.
+  const root = buildExportRoot(`${titleHtml}${attributionHtml}${bodyHtml}`);
+  document.body.appendChild(root);
+
+  try {
+    const html2pdf = await loadHtml2Pdf();
+    const filename = sanitizeFilename(normalizedTitle || defaultTitle) + ".pdf";
+    // `pagebreak` は html2pdf.js v0.10+ の実機能だが、同梱の `.d.ts` には未定義。
+    // また `html2pdf()` のオーバーロード解決の都合で戻り値が
+    // `Html2PdfWorker | Promise` のユニオンに見えるため、ここで
+    // `unknown` 経由のキャストで最小限の構造的型に寄せる。
+    //
+    // `pagebreak` is supported at runtime since html2pdf.js v0.10 but is not
+    // in the bundled `.d.ts`. The `html2pdf()` overload resolution also widens
+    // the return type to a union, so we narrow it through `unknown` to a
+    // chainable worker that matches what the library exposes at runtime.
+    const opts = {
+      filename,
+      margin: [12, 12, 16, 12] as [number, number, number, number],
+      image: { type: "jpeg" as const, quality: 0.95 },
+      enableLinks: true,
+      html2canvas: { scale: 2, useCORS: true, backgroundColor: "#ffffff" },
+      jsPDF: { unit: "mm", format, orientation: "portrait" as const },
+      pagebreak: { mode: ["css", "legacy"], avoid: ["pre", "table", "img", "blockquote"] },
+    };
+
+    interface Html2PdfChain {
+      set(options: typeof opts): Html2PdfChain;
+      from(src: HTMLElement): Html2PdfChain;
+      save(): Promise;
+    }
+    const worker = html2pdf() as unknown as Html2PdfChain;
+    await worker.set(opts).from(root).save();
+  } finally {
+    root.remove();
+  }
+}
diff --git a/src/pages/NotePageView.test.tsx b/src/pages/NotePageView.test.tsx
index 1e926882..2cd2218f 100644
--- a/src/pages/NotePageView.test.tsx
+++ b/src/pages/NotePageView.test.tsx
@@ -22,6 +22,7 @@ const {
   mockSetPageContext,
   mockExportMarkdown,
   mockCopyMarkdown,
+  mockExportPdf,
   mockRemoveFromNoteMutate,
   mockUseMarkdownExport,
 } = vi.hoisted(() => ({
@@ -39,6 +40,7 @@ const {
   mockSetPageContext: vi.fn(),
   mockExportMarkdown: vi.fn(),
   mockCopyMarkdown: vi.fn().mockResolvedValue(undefined),
+  mockExportPdf: vi.fn().mockResolvedValue(undefined),
   mockRemoveFromNoteMutate: vi.fn(),
   // `useMarkdownExport(title, body, sourceUrl)` の呼び出し引数を捕捉するための
   // モック。Codex P1 (PR #893) の「export/copy が `page.content` を読んで空に
@@ -143,6 +145,12 @@ vi.mock("@/components/editor/PageEditor/useMarkdownExport", () => ({
   },
 }));
 
+vi.mock("@/components/editor/PageEditor/usePdfExport", () => ({
+  usePdfExport: () => ({
+    handleExportPdf: mockExportPdf,
+  }),
+}));
+
 // 読み取り専用経路の Markdown export ソースは `usePagePublicContent` 経由で
 // 取得した `content_text` に切り替わった (Codex P1, PR #893)。テストは初期値で
 // 「ロード完了 + 本文あり」を返し、必要なテストだけ `mockReturnValue` で上書きする。
@@ -323,6 +331,7 @@ describe("NotePageView", () => {
     mockApi.updatePageMetadata.mockReset();
     mockExportMarkdown.mockReset();
     mockCopyMarkdown.mockReset().mockResolvedValue(undefined);
+    mockExportPdf.mockReset().mockResolvedValue(undefined);
     mockRemoveFromNoteMutate.mockReset();
     mockUseMarkdownExport.mockReset();
     // 既定: read-only 経路の公開コンテンツは「ロード完了 + 本文あり」。
@@ -500,6 +509,7 @@ describe("NotePageView", () => {
 
       expect(screen.getByText("editor.pageHistory.menuButton")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.exportMarkdown")).toBeInTheDocument();
+      expect(screen.getByText("editor.pageMenu.exportPdf")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.copyMarkdown")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.deletePage")).toBeInTheDocument();
       // 旧「個人に取り込み」項目は削除されていることを明示的に検証する。
@@ -507,7 +517,7 @@ describe("NotePageView", () => {
       expect(screen.queryByText("notes.copyToPersonal")).not.toBeInTheDocument();
     });
 
-    it("read-only 時、削除以外の3項目だけを出す / shows history/export/copy but hides delete in read-only mode", () => {
+    it("read-only 時、削除以外の4項目だけを出す / shows history/export-md/export-pdf/copy but hides delete in read-only mode", () => {
       vi.mocked(useNote).mockReturnValue({
         note: { id: "note-1" },
         access: { canView: true, canEdit: false },
@@ -529,6 +539,7 @@ describe("NotePageView", () => {
 
       expect(screen.getByText("editor.pageHistory.menuButton")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.exportMarkdown")).toBeInTheDocument();
+      expect(screen.getByText("editor.pageMenu.exportPdf")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.copyMarkdown")).toBeInTheDocument();
       // read-only では削除は出さない（権限がないため）。
       // Delete is hidden in read-only mode (no permission).
@@ -577,6 +588,7 @@ describe("NotePageView", () => {
 
       expect(screen.queryByText("editor.pageHistory.menuButton")).not.toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.exportMarkdown")).toBeInTheDocument();
+      expect(screen.getByText("editor.pageMenu.exportPdf")).toBeInTheDocument();
       expect(screen.getByText("editor.pageMenu.copyMarkdown")).toBeInTheDocument();
       expect(screen.queryByText("editor.pageMenu.deletePage")).not.toBeInTheDocument();
     });
@@ -627,6 +639,15 @@ describe("NotePageView", () => {
       expect(mockExportMarkdown).toHaveBeenCalledTimes(1);
     });
 
+    it("`PDFで出力` で `handleExportPdf` を呼ぶ / invokes handleExportPdf on PDF export click", () => {
+      setupEditableRender();
+      renderNotePageView();
+
+      fireEvent.click(screen.getByText("editor.pageMenu.exportPdf"));
+
+      expect(mockExportPdf).toHaveBeenCalledTimes(1);
+    });
+
     it("`Markdownをコピー` で `handleCopyMarkdown` を呼ぶ / invokes handleCopyMarkdown on copy click", () => {
       setupEditableRender();
       renderNotePageView();
@@ -1039,8 +1060,10 @@ describe("NotePageView", () => {
     renderNotePageView();
 
     const exportItem = screen.getByText("editor.pageMenu.exportMarkdown").closest("button");
+    const pdfItem = screen.getByText("editor.pageMenu.exportPdf").closest("button");
     const copyItem = screen.getByText("editor.pageMenu.copyMarkdown").closest("button");
     expect(exportItem).toBeDisabled();
+    expect(pdfItem).toBeDisabled();
     expect(copyItem).toBeDisabled();
   });
 
diff --git a/src/pages/NotePageView.tsx b/src/pages/NotePageView.tsx
index c99bdaca..0aac280f 100644
--- a/src/pages/NotePageView.tsx
+++ b/src/pages/NotePageView.tsx
@@ -1,7 +1,7 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useLocation, useNavigate, useParams } from "react-router-dom";
 import { useQueryClient } from "@tanstack/react-query";
-import { Copy, Download, History, Trash2 } from "lucide-react";
+import { Copy, Download, FileText, History, Trash2 } from "lucide-react";
 import { PageLoadingOrDenied } from "@/components/layout/PageLoadingOrDenied";
 import { PageEditorContent } from "@/components/note/PageEditorContent";
 import { NotePagePublicView } from "@/components/note/NotePagePublicView";
@@ -35,6 +35,7 @@ import { NoteWorkspaceProvider, useNoteWorkspaceOptional } from "@/contexts/Note
 import { useAIChatContext } from "@/contexts/AIChatContext";
 import { NoteWorkspaceToolbar } from "@/components/note/NoteWorkspaceToolbar";
 import { useMarkdownExport } from "@/components/editor/PageEditor/useMarkdownExport";
+import { usePdfExport } from "@/components/editor/PageEditor/usePdfExport";
 import { usePagePublicContent } from "@/hooks/usePagePublicContent";
 import { PageHistoryModal } from "@/components/editor/pageHistory/PageHistoryModal";
 import { convertMarkdownToTiptapContent } from "@/lib/markdownToTiptap";
@@ -85,11 +86,13 @@ function buildSharedMenuItems({
   t,
   onOpenHistory,
   onExportMarkdown,
+  onExportPdf,
   onCopyMarkdown,
 }: {
   t: (key: string) => string;
   onOpenHistory: () => void;
   onExportMarkdown: () => void;
+  onExportPdf: () => void;
   onCopyMarkdown: () => void;
 }): PageDetailToolbarAction[] {
   return [
@@ -105,6 +108,12 @@ function buildSharedMenuItems({
       icon: Download,
       onClick: onExportMarkdown,
     },
+    {
+      id: "export-pdf",
+      label: t("editor.pageMenu.exportPdf"),
+      icon: FileText,
+      onClick: onExportPdf,
+    },
     {
       id: "copy-markdown",
       label: t("editor.pageMenu.copyMarkdown"),
@@ -199,6 +208,7 @@ function NotePageEditorEditable({
     editorContent,
     page.sourceUrl,
   );
+  const { handleExportPdf } = usePdfExport(title, editorContent, page.sourceUrl);
 
   useEffect(() => {
     setPageContext({
@@ -418,6 +428,7 @@ function NotePageEditorEditable({
         t,
         onOpenHistory: handleOpenHistory,
         onExportMarkdown: handleExportMarkdown,
+        onExportPdf: handleExportPdf,
         onCopyMarkdown: handleCopyMarkdown,
       }),
       {
@@ -434,6 +445,7 @@ function NotePageEditorEditable({
       t,
       handleOpenHistory,
       handleExportMarkdown,
+      handleExportPdf,
       handleCopyMarkdown,
       onRequestDelete,
       isDeletePending,
@@ -568,6 +580,11 @@ function NotePageReadOnly({
     exportSource,
     page.sourceUrl,
   );
+  const { handleExportPdf } = usePdfExport(
+    publicContent?.title ?? page.title,
+    exportSource,
+    page.sourceUrl,
+  );
 
   const handleOpenHistory = useCallback(() => {
     setHistoryOpen(true);
@@ -598,6 +615,15 @@ function NotePageReadOnly({
         // exporting an empty Markdown file (Codex P1, PR #893).
         disabled: !isExportSourceReady,
       },
+      {
+        id: "export-pdf",
+        label: t("editor.pageMenu.exportPdf"),
+        icon: FileText,
+        onClick: handleExportPdf,
+        // Markdown と同じ理由で公開コンテンツ未到着時は無効化する。
+        // Same gating as Markdown: block until public-content resolves.
+        disabled: !isExportSourceReady,
+      },
       {
         id: "copy-markdown",
         label: t("editor.pageMenu.copyMarkdown"),
@@ -612,6 +638,7 @@ function NotePageReadOnly({
     canViewHistory,
     handleOpenHistory,
     handleExportMarkdown,
+    handleExportPdf,
     handleCopyMarkdown,
     isExportSourceReady,
   ]);

From b964ce1334e44bb7cafc5a901cd7790eaba3325f Mon Sep 17 00:00:00 2001
From: Claude 
Date: Wed, 20 May 2026 12:04:56 +0000
Subject: [PATCH 02/44] =?UTF-8?q?fix(pdf-export):=20read-only=20=E3=83=91?=
 =?UTF-8?q?=E3=82=B9=E3=81=AE=E6=94=B9=E8=A1=8C=E6=BD=B0=E3=82=8C=E3=83=BB?=
 =?UTF-8?q?=E7=9B=B8=E5=AF=BE=E7=94=BB=E5=83=8F=E3=83=BB=E3=82=B3=E3=83=A1?=
 =?UTF-8?q?=E3=83=B3=E3=83=88=E6=95=B4=E5=90=88=E6=80=A7=20(PR=20#921=20re?=
 =?UTF-8?q?view)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- プレーンテキスト fallback で `\n` を `
            `/`
            ` に展開
  (codex P1: 読み取り専用 `content_text` が 1 行に潰れていた)
- `sanitizeUrl` 正規表現に `.` を追加し `image.png` 等の相対画像を許可
  (gemini-code-assist high)
- heading コメントを h2-h5 → h2-h6 に修正 (gemini-code-assist medium)
- 上記 3 点に対応する単体テストを追加 (CRLF 正規化・空白のみ入力含む)

Read-only PDF export now preserves paragraph breaks for the plain-text
content fed from `usePagePublicContent.content_text` (Y.Doc-extracted text
with `\n` between blocks). Dotted relative image paths render correctly.
Heading dispatch comment matches the actual h2-h6 range.
---
 src/lib/tiptapToHtml.test.ts | 40 +++++++++++++++++++++++--
 src/lib/tiptapToHtml.ts      | 58 +++++++++++++++++++++++++++++-------
 2 files changed, 85 insertions(+), 13 deletions(-)

diff --git a/src/lib/tiptapToHtml.test.ts b/src/lib/tiptapToHtml.test.ts
index 0f716311..acf4f4f7 100644
--- a/src/lib/tiptapToHtml.test.ts
+++ b/src/lib/tiptapToHtml.test.ts
@@ -233,11 +233,47 @@ describe("tiptapToHtml", () => {
     );
   });
 
-  it("returns plain-text fallback when content is not valid JSON", () => {
-    expect(tiptapToHtml("just text")).toContain("just text");
+  it("wraps non-JSON plain text in a single 
            ", () => {
+    expect(tiptapToHtml("just text")).toBe("
            just text
            ");
+  });
+
+  // PR #921 codex P1: 読み取り専用パスは Hocuspocus の `extractTextFromYXml`
+  // で抽出したプレーンテキスト（ブロック間に `\n`）を渡してくる。空行で
+  // 区切られた段落を `
            ` ブロックに、単独の `\n` を `
            ` に落とす。
+  //
+  // PR #921 codex P1: the read-only path feeds plain text whose blocks are
+  // separated by `\n` (and sometimes `\n\n`). Blank-line runs delimit `
            `
+  // paragraphs; single `\n` becomes `
            ` to preserve line structure.
+  it("preserves paragraph and line-break structure for plain-text fallback", () => {
+    const text = "First paragraph\nstill first.\n\nSecond paragraph.\n\n\nThird paragraph.";
+    expect(tiptapToHtml(text)).toBe(
+      "
            First paragraph
            still first.
            Second paragraph.
            Third paragraph.
            ",
+    );
+  });
+
+  it("escapes HTML metacharacters in the plain-text fallback", () => {
+    expect(tiptapToHtml("");
   });
 
+  // PDF エクスポートは同期的にレンダリングするため、`mermaid` ノードは Mermaid の
+  // 非同期 API を呼ばずに「ソースをコードブロック相当のプレースホルダー」として
+  // 残す。図のソースが PDF 上で失われないことだけ保証する (Issue #945)。
+  // The PDF exporter is synchronous, so `mermaid` nodes are rendered as a
+  // placeholder code block that preserves the diagram source instead of a real
+  // SVG (Issue #945).
+  it("renders mermaid node as a language-mermaid code block placeholder", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "mermaid",
+          attrs: { code: "graph TD\n  A-->B" },
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain('
            ');
+    expect(html).toContain("graph TD");
+    expect(html).toContain("A-->B");
+  });
+
+  it("escapes mermaid source when it contains HTML-significant characters", () => {
+    const json = JSON.stringify({
+      type: "doc",
+      content: [
+        {
+          type: "mermaid",
+          attrs: { code: "" },
+        },
+      ],
+    });
+    const html = tiptapToHtml(json);
+    expect(html).toContain("<script>alert(1)</script>");
+    expect(html).not.toContain("");
+  });
+
   it("applies bold, italic, strike, inline-code, and link marks", () => {
     const json = JSON.stringify({
       type: "doc",
diff --git a/src/lib/tiptapToHtml.ts b/src/lib/tiptapToHtml.ts
index b814215a..c3e28cd3 100644
--- a/src/lib/tiptapToHtml.ts
+++ b/src/lib/tiptapToHtml.ts
@@ -117,6 +117,22 @@ Object.assign(nodeHandlers, {
     const langAttr = language ? ` class="language-${escapeHtmlAttr(language)}"` : "";
     return `
            ${escapeHtml(codeText)}
            `;
   },
+  mermaid: (n) => {
+    // PDF エクスポートは html2pdf.js / html2canvas で静的レンダリングするため、
+    // 実際の SVG を生成するには Mermaid の非同期 API を呼ぶ必要がある。エクスポート
+    // 経路を同期に保つ目的で、ここでは Mermaid ソースをコードブロック相当の
+    // プレースホルダー (`
            …
            `) として
+    // 出力する。少なくとも図のソースが PDF 上で失われず、必要に応じて後続パスで
+    // 事前レンダリングへ差し替えやすい形にしておく（Issue #945）。
+    // Render `mermaid` nodes as a `
            ` block.
+    // Generating a real SVG would require an async call into Mermaid; this
+    // exporter is synchronous (html2pdf.js consumes the DOM immediately) so we
+    // emit the source verbatim as a placeholder. The diagram source is then
+    // preserved in the PDF and can be upgraded to pre-rendered SVG later
+    // without touching call sites (Issue #945).
+    const code = typeof n.attrs?.code === "string" ? n.attrs.code : "";
+    return `
            ${escapeHtml(code)}
            `;
+  },
   horizontalRule: () => "
            ",
   hardBreak: () => "
            ",
   text: (n) => applyMarks(escapeHtml(n.text || ""), n.marks || []),

From 78a50ba89d635c49cd04ede6d817a56366f67083 Mon Sep 17 00:00:00 2001
From: Akimasa Sugai <119780981+otomatty@users.noreply.github.com>
Date: Sun, 24 May 2026 18:00:52 +0900
Subject: [PATCH 16/44] feat: Add Wiki Compose P0 LangGraph infrastructure
 (#948) (#954)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(api): wiki compose P0 — LangGraph エージェント基盤 (#948)

Wiki Compose の P0 基盤として、`server/api/src/agents/` 配下に LangGraph
実行基盤を構築する。後続フェーズ (#949〜) が依存する共通レイヤ。

## 追加

- 依存パッケージ: `@langchain/core`, `@langchain/langgraph`,
  `@langchain/langgraph-checkpoint-postgres`, `@langchain/openai`,
  `@langchain/anthropic`, `@langchain/google-genai`, `zod`
- `agents/core/llm/`:
  - `ZediChatModel` — `BaseChatModel` を継承し、全 LLM 呼び出しを既存
    `callProvider` / `streamProvider` 経由に統一する。`validateModelAccess`
    + `recordUsage` を 1 呼び出しあたり 1 回ずつ通し、`/api/ai/chat` と
    課金経路を共通化する。P0 は backend=`zedi_managed` のみ。
  - `modelFactory` — backend ガード (`assertSupportedBackendP0`) +
    provider API キー解決をまとめる。
  - `usageCallback` — `recordZediUsage` と LangChain `BaseMessage` →
    既存 `AIMessage` への変換ユーティリティ。
- `agents/core/checkpoint/postgresCheckpointer.ts` — `PostgresSaver` の
  プロセスローカルシングルトン。checkpoint テーブルは `setup()` で別管理。
- `agents/core/state/baseState.ts` — 全 subgraph 共通の `BaseState`
  (messages / phase / pageId / userId)。
- `agents/core/tools/` — `web_search` / `wiki_search` / `fetch_article` /
  `image_search` を zod schema + LangGraph tool として登録。P0 は本体スタブ。
- `agents/core/types/` — `ExecutionBackend`, `GraphContext`, `SseEvent`
  の discriminated union。
- `agents/registry/graphRegistry.ts` — `graphId` → factory のマップ。
  P0 動作確認用に `wiki-compose-stub` を登録。
- `agents/runner/`:
  - `GraphRunner` — invoke / streamEvents / resume を一括で受け持つ。
    `thread_id` と `GraphContext` を `configurable` に注入する。
  - `sseMapper` — LangGraph 生イベント → `SseEvent` の純粋関数変換。
- Drizzle: `wiki_compose_sessions` テーブル + migration
  `0031_add_wiki_compose_sessions.sql`。
- Routes `/api/pages/:pageId/compose-sessions`:
  - `POST /` — 行作成 (graphId / backend 検証)
  - `GET /:id` — 取得
  - `POST /:id/run` — SSE 実行
  - `PATCH /:id/resume` — interrupt 再開
  - `DELETE /:id` — キャンセル

## テスト

- `agents/` 配下 5 ファイル (42 件): ZediChatModel の usage 記録経路、
  GraphRunner の registry 解決と Command 渡し、sseMapper の event 変換、
  tools の zod schema と名前安定性、backend ホワイトリスト。
- `routes/composeSessions.test.ts` (10 件): 認可・CRUD・backend ガード。
- 全体: 1306 件 (既存 + 新規)。

* chore(api): wire postgres checkpointer + knip hygiene for #948

Knip flagged 3 unused files and 4 unused deps. Address each in line with
the issue's acceptance criteria rather than just suppressing.

- `agents/core/checkpoint/index.ts` — new barrel exposing `resolveCheckpointerForRun()`.
  Returns the `PostgresSaver` singleton when `DATABASE_URL` / `POSTGRES_URL` is
  set (production), and `false` otherwise (tests / CI / smoke runs). Calls
  `ensurePostgresCheckpointerSetup()` once on first production use.
- `routes/composeSessions.ts` — run + resume routes now feed the resolved
  checkpointer to `GraphRunner` instead of hard-coded `false`. Satisfies the
  P0 acceptance criterion: "`PostgresSaver` で thread_id 単位の checkpoint
  保存・再開ができる".
- `agents/index.ts` — re-export `resolveCheckpointerForRun` and register
  `src/agents/index.ts` as a knip entry so the public agent barrel and the
  `core/types/index.ts` re-exports stop being flagged as unreachable.
- `knip.json` — ignore `@langchain/openai` / `@langchain/anthropic` /
  `@langchain/google-genai`. Issue #948 lists them as P0 deps; #949+
  subgraphs will consume them directly.

Verified: knip clean (no unused files / deps), typecheck ✓, 1306 tests ✓.

---------

Co-authored-by: Claude 
---
 knip.json                                     |   7 +-
 server/api/bun.lock                           |  79 +++-
 .../0031_add_wiki_compose_sessions.sql        |  57 +++
 server/api/drizzle/meta/_journal.json         |   7 +
 server/api/package.json                       |   9 +-
 .../agents/core/llm/modelFactory.test.ts      |  36 ++
 .../agents/core/llm/zediChatModel.test.ts     | 265 ++++++++++++
 .../__tests__/agents/core/tools/tools.test.ts | 100 +++++
 .../agents/runner/graphRunner.test.ts         | 180 ++++++++
 .../__tests__/agents/runner/sseMapper.test.ts | 130 ++++++
 .../__tests__/routes/composeSessions.test.ts  | 265 ++++++++++++
 .../api/src/agents/core/checkpoint/index.ts   |  41 ++
 .../core/checkpoint/postgresCheckpointer.ts   |  75 ++++
 .../api/src/agents/core/llm/modelFactory.ts   | 145 +++++++
 .../api/src/agents/core/llm/usageCallback.ts  | 130 ++++++
 .../api/src/agents/core/llm/zediChatModel.ts  | 318 ++++++++++++++
 server/api/src/agents/core/state/baseState.ts |  73 ++++
 .../api/src/agents/core/tools/fetchArticle.ts |  57 +++
 .../api/src/agents/core/tools/imageSearch.ts  |  46 ++
 server/api/src/agents/core/tools/index.ts     |  36 ++
 server/api/src/agents/core/tools/webSearch.ts |  61 +++
 .../api/src/agents/core/tools/wikiSearch.ts   |  53 +++
 .../src/agents/core/types/executionBackend.ts |  33 ++
 .../api/src/agents/core/types/graphContext.ts |  48 +++
 server/api/src/agents/core/types/index.ts     |  27 ++
 server/api/src/agents/core/types/sseEvents.ts | 141 ++++++
 server/api/src/agents/index.ts                |  70 +++
 .../api/src/agents/registry/graphRegistry.ts  | 118 ++++++
 server/api/src/agents/registry/stubGraph.ts   |  42 ++
 server/api/src/agents/runner/graphRunner.ts   | 172 ++++++++
 server/api/src/agents/runner/sseMapper.ts     | 162 +++++++
 server/api/src/app.ts                         |  11 +
 server/api/src/routes/composeSessions.ts      | 400 ++++++++++++++++++
 server/api/src/schema/index.ts                |   6 +
 server/api/src/schema/wikiComposeSessions.ts  | 127 ++++++
 35 files changed, 3523 insertions(+), 4 deletions(-)
 create mode 100644 server/api/drizzle/0031_add_wiki_compose_sessions.sql
 create mode 100644 server/api/src/__tests__/agents/core/llm/modelFactory.test.ts
 create mode 100644 server/api/src/__tests__/agents/core/llm/zediChatModel.test.ts
 create mode 100644 server/api/src/__tests__/agents/core/tools/tools.test.ts
 create mode 100644 server/api/src/__tests__/agents/runner/graphRunner.test.ts
 create mode 100644 server/api/src/__tests__/agents/runner/sseMapper.test.ts
 create mode 100644 server/api/src/__tests__/routes/composeSessions.test.ts
 create mode 100644 server/api/src/agents/core/checkpoint/index.ts
 create mode 100644 server/api/src/agents/core/checkpoint/postgresCheckpointer.ts
 create mode 100644 server/api/src/agents/core/llm/modelFactory.ts
 create mode 100644 server/api/src/agents/core/llm/usageCallback.ts
 create mode 100644 server/api/src/agents/core/llm/zediChatModel.ts
 create mode 100644 server/api/src/agents/core/state/baseState.ts
 create mode 100644 server/api/src/agents/core/tools/fetchArticle.ts
 create mode 100644 server/api/src/agents/core/tools/imageSearch.ts
 create mode 100644 server/api/src/agents/core/tools/index.ts
 create mode 100644 server/api/src/agents/core/tools/webSearch.ts
 create mode 100644 server/api/src/agents/core/tools/wikiSearch.ts
 create mode 100644 server/api/src/agents/core/types/executionBackend.ts
 create mode 100644 server/api/src/agents/core/types/graphContext.ts
 create mode 100644 server/api/src/agents/core/types/index.ts
 create mode 100644 server/api/src/agents/core/types/sseEvents.ts
 create mode 100644 server/api/src/agents/index.ts
 create mode 100644 server/api/src/agents/registry/graphRegistry.ts
 create mode 100644 server/api/src/agents/registry/stubGraph.ts
 create mode 100644 server/api/src/agents/runner/graphRunner.ts
 create mode 100644 server/api/src/agents/runner/sseMapper.ts
 create mode 100644 server/api/src/routes/composeSessions.ts
 create mode 100644 server/api/src/schema/wikiComposeSessions.ts

diff --git a/knip.json b/knip.json
index 9b816fd7..d4b235d5 100644
--- a/knip.json
+++ b/knip.json
@@ -33,7 +33,7 @@
       "project": ["src/**/*.ts"]
     },
     "server/api": {
-      "entry": ["scripts/**/*.ts"],
+      "entry": ["scripts/**/*.ts", "src/agents/index.ts"],
       "project": ["src/**/*.{ts,tsx}", "scripts/**/*.ts"]
     },
     "server/hocuspocus": {
@@ -103,7 +103,10 @@
     "wrangler",
     "@tauri-apps/plugin-shell",
     "@tauri-apps/plugin-store",
-    "@tauri-apps/plugin-updater"
+    "@tauri-apps/plugin-updater",
+    "@langchain/openai",
+    "@langchain/anthropic",
+    "@langchain/google-genai"
   ],
   "ignoreExportsUsedInFile": {
     "interface": true,
diff --git a/server/api/bun.lock b/server/api/bun.lock
index 6e068565..fff6c61d 100644
--- a/server/api/bun.lock
+++ b/server/api/bun.lock
@@ -8,6 +8,12 @@
         "@aws-sdk/client-s3": "^3.1002.0",
         "@aws-sdk/s3-request-presigner": "^3.1002.0",
         "@hono/node-server": "^2.0.0",
+        "@langchain/anthropic": "^1.4.0",
+        "@langchain/core": "^1.1.48",
+        "@langchain/google-genai": "^2.1.31",
+        "@langchain/langgraph": "^1.3.2",
+        "@langchain/langgraph-checkpoint-postgres": "^1.0.1",
+        "@langchain/openai": "^1.4.7",
         "@mozilla/readability": "^0.6.0",
         "@polar-sh/sdk": "^0.47.0",
         "@react-email/components": "^1.0.11",
@@ -33,6 +39,7 @@
         "resend": "^6.10.0",
         "yjs": "^13.6.30",
         "youtubei.js": "^17.0.1",
+        "zod": "^4.4.3",
       },
       "devDependencies": {
         "@types/jsdom": "^28.0.0",
@@ -49,6 +56,8 @@
     },
   },
   "packages": {
+    "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.95.2", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-Egddwo3sheo1PzUrMkZnH6VkQYwS0h/b/i8vSK8Ta9M45UQipAMeDFH57dYuDAfXMEUUGeKw6CMlremgMZgrSQ=="],
+
     "@asamuzakjp/css-color": ["@asamuzakjp/css-color@5.0.1", "", { "dependencies": { "@csstools/css-calc": "^3.1.1", "@csstools/css-color-parser": "^4.0.2", "@csstools/css-parser-algorithms": "^4.0.0", "@csstools/css-tokenizer": "^4.0.0", "lru-cache": "^11.2.6" } }, "sha512-2SZFvqMyvboVV1d15lMf7XiI3m7SDqXUuKaTymJYLN6dSGadqp+fVojqJlVoMlbZnlTmu3S0TLwLTJpvBMO1Aw=="],
 
     "@asamuzakjp/dom-selector": ["@asamuzakjp/dom-selector@7.0.3", "", { "dependencies": { "@asamuzakjp/nwsapi": "^2.3.9", "bidi-js": "^1.0.3", "css-tree": "^3.2.1", "is-potential-custom-element-name": "^1.0.1", "lru-cache": "^11.2.7" } }, "sha512-Q6mU0Z6bfj6YvnX2k9n0JxiIwrCFN59x/nWmYQnAqP000ruX/yV+5bp/GRcF5T8ncvfwJQ7fgfP74DlpKExILA=="],
@@ -139,6 +148,8 @@
 
     "@aws/lambda-invoke-store": ["@aws/lambda-invoke-store@0.2.3", "", {}, "sha512-oLvsaPMTBejkkmHhjf09xTgk71mOqyr/409NKhRIL08If7AhVfUsJhVsx386uJaqNd42v9kWamQ9lFbkoC2dYw=="],
 
+    "@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
+
     "@better-auth/core": ["@better-auth/core@1.5.3", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "zod": "^4.3.6" }, "peerDependencies": { "@better-auth/utils": "0.3.1", "@better-fetch/fetch": "1.1.21", "@cloudflare/workers-types": ">=4", "better-call": "1.3.2", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1" }, "optionalPeers": ["@cloudflare/workers-types"] }, "sha512-fORsQjNZ6BQ7o96xMe7elz3Y4Y8DsqXmQrdyzt289G9rmzX4auwBCPTtE2cXTRTYGiVvH9bv0b97t1Uo/OWynQ=="],
 
     "@better-auth/drizzle-adapter": ["@better-auth/drizzle-adapter@1.5.3", "", { "peerDependencies": { "@better-auth/core": "1.5.3", "@better-auth/utils": "^0.3.0", "drizzle-orm": ">=0.41.0" } }, "sha512-dib9V1vpwDu+TKLC+L+8Q5bLNS0uE3JCT4pGotw52pnpiQF8msoMK4eEfri19f8DtNltpb2F2yzyIsTugBBYNQ=="],
@@ -157,6 +168,8 @@
 
     "@bufbuild/protobuf": ["@bufbuild/protobuf@2.11.0", "", {}, "sha512-sBXGT13cpmPR5BMgHE6UEEfEaShh5Ror6rfN3yEK5si7QVrtZg8LEPQb0VVhiLRUslD2yLnXtnRzG035J/mZXQ=="],
 
+    "@cfworker/json-schema": ["@cfworker/json-schema@4.1.1", "", {}, "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og=="],
+
     "@chevrotain/cst-dts-gen": ["@chevrotain/cst-dts-gen@10.5.0", "", { "dependencies": { "@chevrotain/gast": "10.5.0", "@chevrotain/types": "10.5.0", "lodash": "4.17.21" } }, "sha512-lhmC/FyqQ2o7pGK4Om+hzuDrm9rhFYIJ/AXoQBeongmn870Xeb0L6oGEiuR8nohFNL5sMaQEJWCxr1oIVIVXrw=="],
 
     "@chevrotain/gast": ["@chevrotain/gast@10.5.0", "", { "dependencies": { "@chevrotain/types": "10.5.0", "lodash": "4.17.21" } }, "sha512-pXdMJ9XeDAbgOWKuD1Fldz4ieCs6+nLNmyVhe2gZVqoO7v8HXuHYs5OV2EzUtbuai37TlOAQHrTDvxMnvMJz3A=="],
@@ -245,12 +258,32 @@
 
     "@fastify/otel": ["@fastify/otel@0.18.0", "", { "dependencies": { "@opentelemetry/core": "^2.0.0", "@opentelemetry/instrumentation": "^0.212.0", "@opentelemetry/semantic-conventions": "^1.28.0", "minimatch": "^10.2.4" }, "peerDependencies": { "@opentelemetry/api": "^1.9.0" } }, "sha512-3TASCATfw+ctICSb4ymrv7iCm0qJ0N9CarB+CZ7zIJ7KqNbwI5JjyDL1/sxoC0ccTO1Zyd1iQ+oqncPg5FJXaA=="],
 
+    "@google/generative-ai": ["@google/generative-ai@0.24.1", "", {}, "sha512-MqO+MLfM6kjxcKoy0p1wRzG3b4ZZXtPI+z2IE26UogS2Cm/XHO+7gGRBh6gcJsOiIVoH93UwKvW4HdgiOZCy9Q=="],
+
     "@hono/node-server": ["@hono/node-server@2.0.0", "", { "peerDependencies": { "hono": "^4" } }, "sha512-n3GfHwwCvHCkGmOwKfxUPOlbfzuO64Sbc5XC4NGPIXxkuOnJrdgExdRKmHfF924r914WRJPT397GdqLvdYTeyQ=="],
 
     "@ioredis/commands": ["@ioredis/commands@1.5.1", "", {}, "sha512-JH8ZL/ywcJyR9MmJ5BNqZllXNZQqQbnVZOqpPQqE1vHiFgAw4NHbvE0FOduNU8IX9babitBT46571OnPTT0Zcw=="],
 
     "@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og=="],
 
+    "@langchain/anthropic": ["@langchain/anthropic@1.4.0", "", { "dependencies": { "@anthropic-ai/sdk": "^0.95.1", "zod": "^3.25.76 || ^4" }, "peerDependencies": { "@langchain/core": "^1.1.47" } }, "sha512-rs1yVydrHjyiD31uChdCnKZpmDuKa0Bpz8Raiy9GvqnqmfXPMe0oOrap/2paE+NRSinDbtax8mMpP/yv8EbO1A=="],
+
+    "@langchain/core": ["@langchain/core@1.1.48", "", { "dependencies": { "@cfworker/json-schema": "^4.0.2", "@standard-schema/spec": "^1.1.0", "js-tiktoken": "^1.0.12", "langsmith": ">=0.5.0 <1.0.0", "mustache": "^4.2.0", "p-queue": "^6.6.2", "zod": "^3.25.76 || ^4" } }, "sha512-fQU6Guyb1pwc2fEplmA8FPbKfOMAofjnyJzExevro0FxEiuGHE18Ov/ZHmT9trWCDTZRI9eW1VIc6aChxV8pAQ=="],
+
+    "@langchain/google-genai": ["@langchain/google-genai@2.1.31", "", { "dependencies": { "@google/generative-ai": "^0.24.1" }, "peerDependencies": { "@langchain/core": "^1.1.47" } }, "sha512-lHIJGtZab0jqoufKRPXyHHg1nLXrE74LXd0ftgibWEACc1SpSLu6XwtA23+dX4l7Q/YeSgb9n40YJx5k00/fqw=="],
+
+    "@langchain/langgraph": ["@langchain/langgraph@1.3.2", "", { "dependencies": { "@langchain/langgraph-checkpoint": "^1.0.2", "@langchain/langgraph-sdk": "~1.9.4", "@langchain/protocol": "^0.0.15", "@standard-schema/spec": "1.1.0", "uuid": "^10.0.0" }, "peerDependencies": { "@langchain/core": "^1.1.44", "zod": "^3.25.32 || ^4.2.0", "zod-to-json-schema": "^3.x" }, "optionalPeers": ["zod-to-json-schema"] }, "sha512-SL7Ktsr681R7da+1b2MVOWEbaCoFJOXEJPTGOjg4JIG4C7quWbTYC8DzxhcCxte6D/8cGp0rYDBnbKLXEpNqlA=="],
+
+    "@langchain/langgraph-checkpoint": ["@langchain/langgraph-checkpoint@1.0.2", "", { "dependencies": { "uuid": "^10.0.0" }, "peerDependencies": { "@langchain/core": "^1.1.44" } }, "sha512-F4E5Tr0nt8FGghgdscJtHw+ABzChOHeI80R7Y1pjIHdiJom6c2ieo76vL+FWiny80JmoGqhrVAEIWrw0cXKPxg=="],
+
+    "@langchain/langgraph-checkpoint-postgres": ["@langchain/langgraph-checkpoint-postgres@1.0.1", "", { "dependencies": { "pg": "^8.12.0" }, "peerDependencies": { "@langchain/core": "^1.0.1", "@langchain/langgraph-checkpoint": "^1.0.0" } }, "sha512-cRXOLYZc0egMjyAQfBblWXdoBS+WKwEbCEuE+/f88XHJ1bq5jVz7aycbpjF/7F5EykG7xmybQOz5eUdg3neRzg=="],
+
+    "@langchain/langgraph-sdk": ["@langchain/langgraph-sdk@1.9.5", "", { "dependencies": { "@langchain/protocol": "^0.0.15", "@types/json-schema": "^7.0.15", "p-queue": "^9.0.1", "p-retry": "^7.1.1", "uuid": "^13.0.0" }, "peerDependencies": { "@langchain/core": "^1.1.44", "react": "^18 || ^19", "react-dom": "^18 || ^19", "svelte": "^4.0.0 || ^5.0.0", "vue": "^3.0.0" }, "optionalPeers": ["react", "react-dom", "svelte", "vue"] }, "sha512-NMcz1rEKuVz07ZqcSzNJZCZR9FppRNh+/YWjCKtwZ7a/WNytDEAh26qXTtmDQZ7+J+1nEXhHym1wZDrOxA99wg=="],
+
+    "@langchain/openai": ["@langchain/openai@1.4.7", "", { "dependencies": { "js-tiktoken": "^1.0.12", "openai": "^6.37.0", "zod": "^3.25.76 || ^4" }, "peerDependencies": { "@langchain/core": "^1.1.48" } }, "sha512-i1YLV4pWbGC6W8m0ZNpLObJuf1nyU4o8aWyX4AF9fHn7eM67HfIJWQ5n5XzcCpuSa41otrxA9jvH5XRKwI1qDA=="],
+
+    "@langchain/protocol": ["@langchain/protocol@0.0.15", "", {}, "sha512-MllvbpMjqHevUm+v94M422mH7XKN+wGCvJRBVROTWBotEDOATYB4Ktk2UheYP859y9o2LlhtPek5t1T9eyfAbQ=="],
+
     "@mozilla/readability": ["@mozilla/readability@0.6.0", "", {}, "sha512-juG5VWh4qAivzTAeMzvY9xs9HY5rAcr2E4I7tiSSCokRFi7XIZCAu92ZkSTsIj1OPceCifL3cpfteP3pDT9/QQ=="],
 
     "@mrleebo/prisma-ast": ["@mrleebo/prisma-ast@0.13.1", "", { "dependencies": { "chevrotain": "^10.5.0", "lilconfig": "^2.1.0" } }, "sha512-XyroGQXcHrZdvmrGJvsA9KNeOOgGMg1Vg9OlheUsBOSKznLMDl+YChxbkboRHvtFYJEMRYmlV3uoo/njCw05iw=="],
@@ -623,6 +656,8 @@
 
     "@types/jsdom": ["@types/jsdom@28.0.0", "", { "dependencies": { "@types/node": "*", "@types/tough-cookie": "*", "parse5": "^7.0.0", "undici-types": "^7.21.0" } }, "sha512-A8TBQQC/xAOojy9kM8E46cqT00sF0h7dWjV8t8BJhUi2rG6JRh7XXQo/oLoENuZIQEpXsxLccLCnknyQd7qssQ=="],
 
+    "@types/json-schema": ["@types/json-schema@7.0.15", "", {}, "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA=="],
+
     "@types/linkify-it": ["@types/linkify-it@5.0.0", "", {}, "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q=="],
 
     "@types/markdown-it": ["@types/markdown-it@14.1.2", "", { "dependencies": { "@types/linkify-it": "^5", "@types/mdurl": "^2" } }, "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog=="],
@@ -679,6 +714,8 @@
 
     "balanced-match": ["balanced-match@4.0.4", "", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
 
+    "base64-js": ["base64-js@1.5.1", "", {}, "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA=="],
+
     "better-auth": ["better-auth@1.5.3", "", { "dependencies": { "@better-auth/core": "1.5.3", "@better-auth/kysely-adapter": "1.5.3", "@better-auth/memory-adapter": "1.5.3", "@better-auth/telemetry": "1.5.3", "@better-auth/utils": "0.3.1", "@better-fetch/fetch": "1.1.21", "@noble/ciphers": "^2.1.1", "@noble/hashes": "^2.0.1", "better-call": "1.3.2", "defu": "^6.1.4", "jose": "^6.1.3", "kysely": "^0.28.11", "nanostores": "^1.1.1", "zod": "^4.3.6" }, "peerDependencies": { "@better-auth/drizzle-adapter": "1.5.3", "@better-auth/mongo-adapter": "1.5.3", "@better-auth/prisma-adapter": "1.5.3", "@lynx-js/react": "*", "@prisma/client": "^5.0.0 || ^6.0.0 || ^7.0.0", "@sveltejs/kit": "^2.0.0", "@tanstack/react-start": "^1.0.0", "@tanstack/solid-start": "^1.0.0", "better-sqlite3": "^12.0.0", "drizzle-kit": ">=0.31.4", "drizzle-orm": ">=0.41.0", "mongodb": "^6.0.0 || ^7.0.0", "mysql2": "^3.0.0", "next": "^14.0.0 || ^15.0.0 || ^16.0.0", "pg": "^8.0.0", "prisma": "^5.0.0 || ^6.0.0 || ^7.0.0", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0", "solid-js": "^1.0.0", "svelte": "^4.0.0 || ^5.0.0", "vitest": "^2.0.0 || ^3.0.0 || ^4.0.0", "vue": "^3.0.0" }, "optionalPeers": ["@better-auth/drizzle-adapter", "@better-auth/mongo-adapter", "@better-auth/prisma-adapter", "@lynx-js/react", "@prisma/client", "@sveltejs/kit", "@tanstack/react-start", "@tanstack/solid-start", "better-sqlite3", "drizzle-kit", "drizzle-orm", "mongodb", "mysql2", "next", "pg", "prisma", "react", "react-dom", "solid-js", "svelte", "vitest", "vue"] }, "sha512-E+9kA9GMX1+gT3FfMCqRz0NufT4X/+tNhpOsHW1jLmyPZKinkHtfZkUffSBnG5qGkvfBaH/slT5c1fKttnmF5w=="],
 
     "better-call": ["better-call@1.3.2", "", { "dependencies": { "@better-auth/utils": "^0.3.1", "@better-fetch/fetch": "^1.1.21", "rou3": "^0.7.12", "set-cookie-parser": "^3.0.1" }, "peerDependencies": { "zod": "^4.0.0" }, "optionalPeers": ["zod"] }, "sha512-4cZIfrerDsNTn3cm+MhLbUePN0gdwkhSXEuG7r/zuQ8c/H7iU0/jSK5TD3FW7U0MgKHce/8jGpPYNO4Ve+4NBw=="],
@@ -767,6 +804,8 @@
 
     "estree-walker": ["estree-walker@3.0.3", "", { "dependencies": { "@types/estree": "^1.0.0" } }, "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g=="],
 
+    "eventemitter3": ["eventemitter3@4.0.7", "", {}, "sha512-8guHBZCwKnFhYdHr2ysuRWErTwhoN2X8XELRlrRwpmfeY2jjuUN4taQMsULKUVo1K4DvZl+0pgfyoysHxvmvEw=="],
+
     "expect-type": ["expect-type@1.3.0", "", {}, "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA=="],
 
     "exsolve": ["exsolve@1.0.8", "", {}, "sha512-LmDxfWXwcTArk8fUEnOfSZpHOJ6zOMUJKOtFLFqJLoKJetuQG874Uc7/Kki7zFLzYybmZhp1M7+98pfMqeX8yA=="],
@@ -821,6 +860,8 @@
 
     "ioredis": ["ioredis@5.10.0", "", { "dependencies": { "@ioredis/commands": "1.5.1", "cluster-key-slot": "^1.1.0", "debug": "^4.3.4", "denque": "^2.1.0", "lodash.defaults": "^4.2.0", "lodash.isarguments": "^3.1.0", "redis-errors": "^1.2.0", "redis-parser": "^3.0.0", "standard-as-callback": "^2.1.0" } }, "sha512-HVBe9OFuqs+Z6n64q09PQvP1/R4Bm+30PAyyD4wIEqssh3v9L21QjCVk4kRLucMBcDokJTcLjsGeVRlq/nH6DA=="],
 
+    "is-network-error": ["is-network-error@1.3.2", "", {}, "sha512-PhBY86zaxNZUuWP6h13Vu5oFe0XY6/UlKzQnYFELzGVHygP3MxmvTfYSG7GN3aIab/iWudSMgjSnG9Dq+nHrgA=="],
+
     "is-potential-custom-element-name": ["is-potential-custom-element-name@1.0.1", "", {}, "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ=="],
 
     "is-property": ["is-property@1.0.2", "", {}, "sha512-Ks/IoX00TtClbGQr4TWXemAnktAQvYB7HzcCxDGqEZU6oCmb2INHuOoKxbtR+HFkmYWBKv/dOZtGRiAjDhj92g=="],
@@ -833,10 +874,16 @@
 
     "jose": ["jose@6.2.1", "", {}, "sha512-jUaKr1yrbfaImV7R2TN/b3IcZzsw38/chqMpo2XJ7i2F8AfM/lA4G1goC3JVEwg0H7UldTmSt3P68nt31W7/mw=="],
 
+    "js-tiktoken": ["js-tiktoken@1.0.21", "", { "dependencies": { "base64-js": "^1.5.1" } }, "sha512-biOj/6M5qdgx5TKjDnFT1ymSpM5tbd3ylwDtrQvFQSu0Z7bBYko2dF+W/aUkXUPuk6IVpRxk/3Q2sHOzGlS36g=="],
+
     "jsdom": ["jsdom@29.0.0", "", { "dependencies": { "@asamuzakjp/css-color": "^5.0.1", "@asamuzakjp/dom-selector": "^7.0.2", "@bramus/specificity": "^2.4.2", "@csstools/css-syntax-patches-for-csstree": "^1.1.1", "@exodus/bytes": "^1.15.0", "css-tree": "^3.2.1", "data-urls": "^7.0.0", "decimal.js": "^10.6.0", "html-encoding-sniffer": "^6.0.0", "is-potential-custom-element-name": "^1.0.1", "lru-cache": "^11.2.7", "parse5": "^8.0.0", "saxes": "^6.0.0", "symbol-tree": "^3.2.4", "tough-cookie": "^6.0.1", "undici": "^7.24.3", "w3c-xmlserializer": "^5.0.0", "webidl-conversions": "^8.0.1", "whatwg-mimetype": "^5.0.0", "whatwg-url": "^16.0.1", "xml-name-validator": "^5.0.0" }, "peerDependencies": { "canvas": "^3.0.0" }, "optionalPeers": ["canvas"] }, "sha512-9FshNB6OepopZ08unmmGpsF7/qCjxGPbo3NbgfJAnPeHXnsODE9WWffXZtRFRFe0ntzaAOcSKNJFz8wiyvF1jQ=="],
 
+    "json-schema-to-ts": ["json-schema-to-ts@3.1.1", "", { "dependencies": { "@babel/runtime": "^7.18.3", "ts-algebra": "^2.0.0" } }, "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g=="],
+
     "kysely": ["kysely@0.28.11", "", {}, "sha512-zpGIFg0HuoC893rIjYX1BETkVWdDnzTzF5e0kWXJFg5lE0k1/LfNWBejrcnOFu8Q2Rfq/hTDTU7XLUM8QOrpzg=="],
 
+    "langsmith": ["langsmith@0.7.2", "", { "dependencies": { "p-queue": "6.6.2" }, "peerDependencies": { "@opentelemetry/api": "*", "@opentelemetry/exporter-trace-otlp-proto": "*", "@opentelemetry/sdk-trace-base": "*", "openai": "*", "ws": ">=7" }, "optionalPeers": ["@opentelemetry/api", "@opentelemetry/exporter-trace-otlp-proto", "@opentelemetry/sdk-trace-base", "openai", "ws"] }, "sha512-3dZUwQDJluxi2ih5eIygFODtlrQKrs3Tua0Ck3l+DAUkSGFkB1Dc0JPqkGbqiVSN+TQDElnkev/ydAOAz6jndA=="],
+
     "leac": ["leac@0.6.0", "", {}, "sha512-y+SqErxb8h7nE/fiEX07jsbuhrpO9lL8eca7/Y1nuWV2moNlXhyd59iDGcRf6moVyDMbmTNzL40SUyrFU/yDpg=="],
 
     "lib0": ["lib0@0.2.117", "", { "dependencies": { "isomorphic.js": "^0.2.4" }, "bin": { "0serve": "bin/0serve.js", "0gentesthtml": "bin/gentesthtml.js", "0ecdsa-generate-keypair": "bin/0ecdsa-generate-keypair.js" } }, "sha512-DeXj9X5xDCjgKLU/7RR+/HQEVzuuEUiwldwOGsHK/sfAfELGWEyTcf0x+uOvCvK3O2zPmZePXWL85vtia6GyZw=="],
@@ -879,6 +926,8 @@
 
     "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
 
+    "mustache": ["mustache@4.2.0", "", { "bin": { "mustache": "bin/mustache" } }, "sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ=="],
+
     "mysql2": ["mysql2@3.15.3", "", { "dependencies": { "aws-ssl-profiles": "^1.1.1", "denque": "^2.1.0", "generate-function": "^2.3.1", "iconv-lite": "^0.7.0", "long": "^5.2.1", "lru.min": "^1.0.0", "named-placeholders": "^1.1.3", "seq-queue": "^0.0.5", "sqlstring": "^2.3.2" } }, "sha512-FBrGau0IXmuqg4haEZRBfHNWB5mUARw6hNwPDXXGg0XzVJ50mr/9hb267lvpVMnhZ1FON3qNd4Xfcez1rbFwSg=="],
 
     "named-placeholders": ["named-placeholders@1.1.6", "", { "dependencies": { "lru.min": "^1.1.0" } }, "sha512-Tz09sEL2EEuv5fFowm419c1+a/jSMiBjI9gHxVLrVdbUkkNUUfjsVYs9pVZu5oCon/kmRh9TfLEObFtkVxmY0w=="],
@@ -895,8 +944,18 @@
 
     "ohash": ["ohash@2.0.11", "", {}, "sha512-RdR9FQrFwNBNXAr4GixM8YaRZRJ5PUWbKYbE5eOsrwAjJW0q2REGcf79oYPsLyskQCZG1PLN+S/K1V00joZAoQ=="],
 
+    "openai": ["openai@6.39.0", "", { "peerDependencies": { "ws": "^8.18.0", "zod": "^3.25 || ^4.0" }, "optionalPeers": ["ws", "zod"], "bin": { "openai": "bin/cli" } }, "sha512-O61LIsimY3acVabwvomwFhwrnN36yvHY2quIfy9keEcFytGgWeV35yLHQ6NVMLSBxRpHmcg2yuhCnlu2HT4pLQ=="],
+
     "orderedmap": ["orderedmap@2.1.1", "", {}, "sha512-TvAWxi0nDe1j/rtMcWcIj94+Ffe6n7zhow33h40SKxmsmozs6dz/e+EajymfoFcHd7sxNn8yHM8839uixMOV6g=="],
 
+    "p-finally": ["p-finally@1.0.0", "", {}, "sha512-LICb2p9CB7FS+0eR1oqWnHhp0FljGLZCWBE9aix0Uye9W8LTQPwMTYVGWQWIw9RdQiDg4+epXQODwIYJtSJaow=="],
+
+    "p-queue": ["p-queue@6.6.2", "", { "dependencies": { "eventemitter3": "^4.0.4", "p-timeout": "^3.2.0" } }, "sha512-RwFpb72c/BhQLEXIZ5K2e+AhgNVmIejGlTgiB9MzZ0e93GRvqZ7uSi0dvRF7/XIXDeNkra2fNHBxTyPDGySpjQ=="],
+
+    "p-retry": ["p-retry@7.1.1", "", { "dependencies": { "is-network-error": "^1.1.0" } }, "sha512-J5ApzjyRkkf601HpEeykoiCvzHQjWxPAHhyjFcEUP2SWq0+35NKh8TLhpLw+Dkq5TZBFvUM6UigdE9hIVYTl5w=="],
+
+    "p-timeout": ["p-timeout@3.2.0", "", { "dependencies": { "p-finally": "^1.0.0" } }, "sha512-rhIwUycgwwKcP9yTOOFK/AKsAopjjCakVqLHePO3CC6Mir1Z99xT+R63jZxAT5lFZLa2inS5h+ZS2GvR99/FBg=="],
+
     "parse5": ["parse5@7.3.0", "", { "dependencies": { "entities": "^6.0.0" } }, "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw=="],
 
     "parseley": ["parseley@0.12.1", "", { "dependencies": { "leac": "^0.6.0", "peberminta": "^0.9.0" } }, "sha512-e6qHKe3a9HWr0oMRVDTRhKce+bRO8VGQR3NyVwcjwrbhMmFCX9KszEV35+rn4AdilFAq9VPxP/Fe1wC9Qjd2lw=="],
@@ -1089,6 +1148,8 @@
 
     "tr46": ["tr46@6.0.0", "", { "dependencies": { "punycode": "^2.3.1" } }, "sha512-bLVMLPtstlZ4iMQHpFHTR7GAGj2jxi8Dg0s2h2MafAE4uSWF98FC/3MomU51iQAMf8/qDUbKWf5GxuvvVcXEhw=="],
 
+    "ts-algebra": ["ts-algebra@2.0.0", "", {}, "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw=="],
+
     "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="],
 
     "tsx": ["tsx@4.21.0", "", { "dependencies": { "esbuild": "~0.27.0", "get-tsconfig": "^4.7.5" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "bin": { "tsx": "dist/cli.mjs" } }, "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw=="],
@@ -1139,7 +1200,7 @@
 
     "zeptomatch": ["zeptomatch@2.1.0", "", { "dependencies": { "grammex": "^3.1.11", "graphmatch": "^1.1.0" } }, "sha512-KiGErG2J0G82LSpniV0CtIzjlJ10E04j02VOudJsPyPwNZgGnRKQy7I1R7GMyg/QswnE4l7ohSGrQbQbjXPPDA=="],
 
-    "zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+    "zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
 
     "@aws-crypto/sha1-browser/@smithy/util-utf8": ["@smithy/util-utf8@2.3.0", "", { "dependencies": { "@smithy/util-buffer-from": "^2.2.0", "tslib": "^2.6.2" } }, "sha512-R8Rdn8Hy72KKcebgLiv8jQcQkXoLMOGGv5uI1/k0l+snqkOzQ1R0ChUBCxWMlBsFMekWjq0wRudIweFs7sKT5A=="],
 
@@ -1211,14 +1272,24 @@
 
     "@aws-sdk/util-user-agent-node/@smithy/node-config-provider": ["@smithy/node-config-provider@4.3.11", "", { "dependencies": { "@smithy/property-provider": "^4.2.11", "@smithy/shared-ini-file-loader": "^4.4.6", "@smithy/types": "^4.13.0", "tslib": "^2.6.2" } }, "sha512-xD17eE7kaLgBBGf5CZQ58hh2YmwK1Z0O8YhffwB/De2jsL0U3JklmhVYJ9Uf37OtUDLF2gsW40Xwwag9U869Gg=="],
 
+    "@better-auth/core/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
     "@esbuild-kit/core-utils/esbuild": ["esbuild@0.18.20", "", { "optionalDependencies": { "@esbuild/android-arm": "0.18.20", "@esbuild/android-arm64": "0.18.20", "@esbuild/android-x64": "0.18.20", "@esbuild/darwin-arm64": "0.18.20", "@esbuild/darwin-x64": "0.18.20", "@esbuild/freebsd-arm64": "0.18.20", "@esbuild/freebsd-x64": "0.18.20", "@esbuild/linux-arm": "0.18.20", "@esbuild/linux-arm64": "0.18.20", "@esbuild/linux-ia32": "0.18.20", "@esbuild/linux-loong64": "0.18.20", "@esbuild/linux-mips64el": "0.18.20", "@esbuild/linux-ppc64": "0.18.20", "@esbuild/linux-riscv64": "0.18.20", "@esbuild/linux-s390x": "0.18.20", "@esbuild/linux-x64": "0.18.20", "@esbuild/netbsd-x64": "0.18.20", "@esbuild/openbsd-x64": "0.18.20", "@esbuild/sunos-x64": "0.18.20", "@esbuild/win32-arm64": "0.18.20", "@esbuild/win32-ia32": "0.18.20", "@esbuild/win32-x64": "0.18.20" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-ceqxoedUrcayh7Y7ZX6NdbbDzGROiyVBgC4PriJThBKSVPWnnFHZAkfI1lJT8QFkOwH4qOS2SJkS4wvpGl8BpA=="],
 
     "@fastify/otel/@opentelemetry/instrumentation": ["@opentelemetry/instrumentation@0.212.0", "", { "dependencies": { "@opentelemetry/api-logs": "0.212.0", "import-in-the-middle": "^2.0.6", "require-in-the-middle": "^8.0.0" }, "peerDependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-IyXmpNnifNouMOe0I/gX7ENfv2ZCNdYTF0FpCsoBcpbIHzk81Ww9rQTYTnvghszCg7qGrIhNvWC8dhEifgX9Jg=="],
 
+    "@langchain/core/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
+    "@langchain/langgraph-sdk/p-queue": ["p-queue@9.3.0", "", { "dependencies": { "eventemitter3": "^5.0.4", "p-timeout": "^7.0.0" } }, "sha512-7NED7xhQ74Ngp4JP/2e0VZHp7vSWfJfqeiR92jPgxsz6m0Se4P03YoTKa9dDXyZ3r6P616gUXttrB6nnHYKang=="],
+
+    "@langchain/langgraph-sdk/uuid": ["uuid@13.0.2", "", { "bin": { "uuid": "dist-node/bin/uuid" } }, "sha512-vzi9uRZ926x4XV73S/4qQaTwPXM2JBj6/6lI/byHH1jOpCzb0zDbfytgA9LcN/hzb2l7WQSQnxITOVx5un/wGw=="],
+
     "@opentelemetry/instrumentation-http/@opentelemetry/core": ["@opentelemetry/core@2.6.1", "", { "dependencies": { "@opentelemetry/semantic-conventions": "^1.29.0" }, "peerDependencies": { "@opentelemetry/api": ">=1.0.0 <1.10.0" } }, "sha512-8xHSGWpJP9wBxgBpnqGL0R3PbdWQndL1Qp50qrg71+B28zK5OQmUgcDKLJgzyAAV38t4tOyLMGDD60LneR5W8g=="],
 
     "@opentelemetry/instrumentation-pg/@types/pg": ["@types/pg@8.15.6", "", { "dependencies": { "@types/node": "*", "pg-protocol": "*", "pg-types": "^2.2.0" } }, "sha512-NoaMtzhxOrubeL/7UZuNTrejB4MPAJ0RpxZqXQf2qXuVlTPuG6Y8p4u9dKRaue4yjmC7ZhzVO2/Yyyn25znrPQ=="],
 
+    "@polar-sh/sdk/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
     "@prisma/dev/@hono/node-server": ["@hono/node-server@1.19.9", "", { "peerDependencies": { "hono": "^4" } }, "sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw=="],
 
     "@prisma/dev/hono": ["hono@4.11.4", "", {}, "sha512-U7tt8JsyrxSRKspfhtLET79pU8K+tInj5QZXs1jSugO1Vq5dFj3kmZsRldo29mTBfcjDRVRXrEZ6LS63Cog9ZA=="],
@@ -1307,6 +1378,8 @@
 
     "better-auth/jose": ["jose@6.1.3", "", {}, "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ=="],
 
+    "better-auth/zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
+
     "dom-serializer/entities": ["entities@4.5.0", "", {}, "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw=="],
 
     "happy-dom/entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],
@@ -1399,6 +1472,10 @@
 
     "@fastify/otel/@opentelemetry/instrumentation/import-in-the-middle": ["import-in-the-middle@2.0.6", "", { "dependencies": { "acorn": "^8.15.0", "acorn-import-attributes": "^1.9.5", "cjs-module-lexer": "^2.2.0", "module-details-from-path": "^1.0.4" } }, "sha512-3vZV3jX0XRFW3EJDTwzWoZa+RH1b8eTTx6YOCjglrLyPuepwoBti1k3L2dKwdCUrnVEfc5CuRuGstaC/uQJJaw=="],
 
+    "@langchain/langgraph-sdk/p-queue/eventemitter3": ["eventemitter3@5.0.4", "", {}, "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw=="],
+
+    "@langchain/langgraph-sdk/p-queue/p-timeout": ["p-timeout@7.0.1", "", {}, "sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg=="],
+
     "@opentelemetry/instrumentation-pg/@types/pg/pg-protocol": ["pg-protocol@1.13.0", "", {}, "sha512-zzdvXfS6v89r6v7OcFCHfHlyG/wvry1ALxZo4LqgUoy7W9xhBDMaqOuMiF3qEV45VqsN6rdlcehHrfDtlCPc8w=="],
 
     "@prisma/instrumentation/@opentelemetry/instrumentation/@opentelemetry/api-logs": ["@opentelemetry/api-logs@0.207.0", "", { "dependencies": { "@opentelemetry/api": "^1.3.0" } }, "sha512-lAb0jQRVyleQQGiuuvCOTDVspc14nx6XJjP4FspJ1sNARo3Regq4ZZbrc3rN4b1TYSuUCvgH+UXUPug4SLOqEQ=="],
diff --git a/server/api/drizzle/0031_add_wiki_compose_sessions.sql b/server/api/drizzle/0031_add_wiki_compose_sessions.sql
new file mode 100644
index 00000000..0b1b153c
--- /dev/null
+++ b/server/api/drizzle/0031_add_wiki_compose_sessions.sql
@@ -0,0 +1,57 @@
+-- 0031: Add `wiki_compose_sessions` — meta-row table for Wiki Compose runs.
+-- Wiki Compose (LangGraph) の実行メタテーブルを追加する。
+--
+-- 1 行 = 1 セッション。session.id は LangGraph の thread_id として再利用される。
+-- LangGraph の checkpoint 系テーブル (checkpoints / checkpoint_blobs /
+-- checkpoint_writes) は `PostgresSaver.setup()` 側で別管理するため、本
+-- migration では作成しない。
+--
+-- One row per compose run. The session id doubles as the LangGraph
+-- `thread_id`. The internal `checkpoints*` tables are owned by
+-- `PostgresSaver.setup()` and intentionally excluded from this migration.
+--
+-- Issue: otomatty/zedi#948 (P0 — LangGraph 基盤)
+--
+-- Idempotent / re-run safety: CREATE TABLE/INDEX IF NOT EXISTS and the FK ADD
+-- block is wrapped in a duplicate-object guard.
+
+CREATE TABLE IF NOT EXISTS "wiki_compose_sessions" (
+    "id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+    "page_id" uuid NOT NULL,
+    "user_id" text NOT NULL,
+    "graph_id" text NOT NULL,
+    "phase" text DEFAULT 'init' NOT NULL,
+    "backend" text DEFAULT 'zedi_managed' NOT NULL,
+    "status" text DEFAULT 'pending' NOT NULL,
+    "metadata" jsonb,
+    "last_error" text,
+    "created_at" timestamp with time zone DEFAULT now() NOT NULL,
+    "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+    "closed_at" timestamp with time zone
+);
+--> statement-breakpoint
+DO $$ BEGIN
+    ALTER TABLE "wiki_compose_sessions"
+        ADD CONSTRAINT "wiki_compose_sessions_page_id_pages_id_fk"
+        FOREIGN KEY ("page_id") REFERENCES "pages"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+    ALTER TABLE "wiki_compose_sessions"
+        ADD CONSTRAINT "wiki_compose_sessions_user_id_users_id_fk"
+        FOREIGN KEY ("user_id") REFERENCES "users"("id") ON DELETE cascade ON UPDATE no action;
+EXCEPTION
+    WHEN duplicate_object THEN NULL;
+END $$;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_wiki_compose_sessions_page_id"
+    ON "wiki_compose_sessions" ("page_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_wiki_compose_sessions_user_id"
+    ON "wiki_compose_sessions" ("user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_wiki_compose_sessions_page_active_updated"
+    ON "wiki_compose_sessions" ("page_id", "updated_at" DESC)
+    WHERE "status" IN ('pending', 'running', 'interrupted');
diff --git a/server/api/drizzle/meta/_journal.json b/server/api/drizzle/meta/_journal.json
index 24641874..80ce39df 100644
--- a/server/api/drizzle/meta/_journal.json
+++ b/server/api/drizzle/meta/_journal.json
@@ -211,6 +211,13 @@
       "when": 1779840000000,
       "tag": "0030_add_notes_tag_filter_bar",
       "breakpoints": true
+    },
+    {
+      "idx": 30,
+      "version": "7",
+      "when": 1779926400000,
+      "tag": "0031_add_wiki_compose_sessions",
+      "breakpoints": true
     }
   ]
 }
diff --git a/server/api/package.json b/server/api/package.json
index 32f47341..48cdd7ce 100644
--- a/server/api/package.json
+++ b/server/api/package.json
@@ -20,6 +20,12 @@
     "@aws-sdk/client-s3": "^3.1002.0",
     "@aws-sdk/s3-request-presigner": "^3.1002.0",
     "@hono/node-server": "^2.0.0",
+    "@langchain/anthropic": "^1.4.0",
+    "@langchain/core": "^1.1.48",
+    "@langchain/google-genai": "^2.1.31",
+    "@langchain/langgraph": "^1.3.2",
+    "@langchain/langgraph-checkpoint-postgres": "^1.0.1",
+    "@langchain/openai": "^1.4.7",
     "@mozilla/readability": "^0.6.0",
     "@polar-sh/sdk": "^0.47.0",
     "@react-email/components": "^1.0.11",
@@ -44,7 +50,8 @@
     "react-dom": "^19.2.4",
     "resend": "^6.10.0",
     "yjs": "^13.6.30",
-    "youtubei.js": "^17.0.1"
+    "youtubei.js": "^17.0.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/jsdom": "^28.0.0",
diff --git a/server/api/src/__tests__/agents/core/llm/modelFactory.test.ts b/server/api/src/__tests__/agents/core/llm/modelFactory.test.ts
new file mode 100644
index 00000000..56330cd8
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/llm/modelFactory.test.ts
@@ -0,0 +1,36 @@
+/**
+ * `modelFactory` のテスト。`assertSupportedBackendP0` の挙動と `UnsupportedBackendError`
+ * の型を固定する。`createZediChatModel` の DB / 環境変数まわりは統合テスト範囲
+ * (route テスト) で見るため、ここは backend ガードに集中する。
+ *
+ * Tests for {@link assertSupportedBackendP0} and {@link UnsupportedBackendError}.
+ * Full `createZediChatModel` is exercised through route tests (out of scope for
+ * P0 unit tests); here we pin the backend whitelist so #951 cannot accidentally
+ * widen it without a deliberate change.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  assertSupportedBackendP0,
+  UnsupportedBackendError,
+} from "../../../../agents/core/llm/modelFactory.js";
+
+describe("assertSupportedBackendP0", () => {
+  it("accepts 'zedi_managed'", () => {
+    expect(assertSupportedBackendP0("zedi_managed")).toBe("zedi_managed");
+  });
+
+  it.each(["byok", "byo_runner", "unknown", "", "ZEDI_MANAGED"])(
+    "throws UnsupportedBackendError for %s",
+    (backend) => {
+      let caught: unknown;
+      try {
+        assertSupportedBackendP0(backend);
+      } catch (err) {
+        caught = err;
+      }
+      expect(caught).toBeInstanceOf(UnsupportedBackendError);
+      expect((caught as UnsupportedBackendError).backend).toBe(backend);
+      expect((caught as UnsupportedBackendError).code).toBe("UNSUPPORTED_BACKEND");
+    },
+  );
+});
diff --git a/server/api/src/__tests__/agents/core/llm/zediChatModel.test.ts b/server/api/src/__tests__/agents/core/llm/zediChatModel.test.ts
new file mode 100644
index 00000000..479b5bb7
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/llm/zediChatModel.test.ts
@@ -0,0 +1,265 @@
+/**
+ * `ZediChatModel` のテスト。mock provider を注入し、`/api/ai/chat` と同じ usage
+ * 記録経路を通っていることを確認する。`recordUsage` 自体は `usageService.test.ts`
+ * 側で検証済みなので、本ファイルでは DB チェーンの呼び出し回数・cost 計算結果を
+ * 主に見る。
+ *
+ * Tests for {@link ZediChatModel}. Injects fake `callProvider` / `streamProvider`
+ * and asserts (1) the provider was called with the converted message shape,
+ * (2) `recordUsage` is invoked exactly once per call, (3) the LangChain
+ * `_generate` / `_streamResponseChunks` outputs surface usage metadata.
+ */
+import { describe, it, expect } from "vitest";
+import { HumanMessage, SystemMessage, AIMessage } from "@langchain/core/messages";
+import { ZediChatModel } from "../../../../agents/core/llm/zediChatModel.js";
+import { createMockDb } from "../../../createMockDb.js";
+import type {
+  AIChatOptions,
+  AIMessage as ZediAIMessage,
+  AIProviderType,
+  Database,
+} from "../../../../types/index.js";
+
+function asDb(results: unknown[]) {
+  const { db, chains } = createMockDb(results);
+  return { db: db as unknown as Database, chains };
+}
+
+interface CallSpy {
+  provider: AIProviderType;
+  apiKey: string;
+  model: string;
+  messages: ZediAIMessage[];
+  options: AIChatOptions;
+}
+
+function buildModel(
+  callResult: {
+    content: string;
+    usage: { inputTokens: number; outputTokens: number };
+    finishReason: string;
+  },
+  spy: { calls: CallSpy[] },
+) {
+  const { db, chains } = asDb([undefined, undefined]);
+  const model = new ZediChatModel({
+    provider: "openai",
+    apiKey: "test-key",
+    apiModelId: "gpt-test",
+    modelRowId: "model-1",
+    inputCostUnits: 10,
+    outputCostUnits: 30,
+    userId: "user-1",
+    tier: "free",
+    db,
+    feature: "wiki_compose:test",
+    callProvider: async (provider, apiKey, model, messages, options = {}) => {
+      spy.calls.push({ provider, apiKey, model, messages, options });
+      return callResult;
+    },
+    streamProvider: async function* () {
+      // Unused in non-streaming tests.
+    },
+  });
+  return { model, db, chains };
+}
+
+describe("ZediChatModel._generate", () => {
+  it("calls the injected provider with converted messages and records usage", async () => {
+    const spy = { calls: [] as CallSpy[] };
+    const { model, chains } = buildModel(
+      {
+        content: "Hello, world!",
+        usage: { inputTokens: 100, outputTokens: 50 },
+        finishReason: "stop",
+      },
+      spy,
+    );
+
+    const result = await model.invoke([new SystemMessage("Be concise."), new HumanMessage("Hi")]);
+
+    // Provider called exactly once with converted role/content.
+    // プロバイダは 1 回だけ呼ばれ、role と content が変換済みである。
+    expect(spy.calls).toHaveLength(1);
+    const call = spy.calls[0];
+    expect(call?.provider).toBe("openai");
+    expect(call?.model).toBe("gpt-test");
+    expect(call?.messages).toEqual([
+      { role: "system", content: "Be concise." },
+      { role: "user", content: "Hi" },
+    ]);
+
+    // usage was persisted: insert(aiUsageLogs) + insert(aiMonthlyUsage upsert).
+    // usage 記録 (aiUsageLogs + aiMonthlyUsage の 2 チェーン) が走っている。
+    expect(chains.length).toBe(2);
+    expect(chains[0]?.startMethod).toBe("insert");
+    expect(chains[1]?.startMethod).toBe("insert");
+
+    const valuesArg = chains[0]?.ops.find((op) => op.method === "values")?.args[0] as
+      | Record
+      | undefined;
+    expect(valuesArg?.modelId).toBe("model-1");
+    expect(valuesArg?.feature).toBe("wiki_compose:test");
+    expect(valuesArg?.inputTokens).toBe(100);
+    expect(valuesArg?.outputTokens).toBe(50);
+    // calculateCost: (100/1000)*10 + (50/1000)*30 = 1 + 1.5 = 2.5 → ceil → 3
+    expect(valuesArg?.costUnits).toBe(3);
+    expect(valuesArg?.apiMode).toBe("system");
+
+    // LangChain message exposes usage in response_metadata.
+    // LangChain メッセージ側にも usage 情報が乗る。
+    expect(result.content).toBe("Hello, world!");
+    expect(result.response_metadata?.usage).toMatchObject({
+      inputTokens: 100,
+      outputTokens: 50,
+      costUnits: 3,
+    });
+  });
+
+  it("treats AI messages as 'assistant' role when converting", async () => {
+    const spy = { calls: [] as CallSpy[] };
+    const { model } = buildModel(
+      {
+        content: "next",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        finishReason: "stop",
+      },
+      spy,
+    );
+
+    await model.invoke([new HumanMessage("Q1"), new AIMessage("A1"), new HumanMessage("Q2")]);
+
+    expect(spy.calls[0]?.messages).toEqual([
+      { role: "user", content: "Q1" },
+      { role: "assistant", content: "A1" },
+      { role: "user", content: "Q2" },
+    ]);
+  });
+
+  it("uses 'user_key' apiMode when constructed with apiMode='user_key' (BYOK forward-compat)", async () => {
+    const spy = { calls: [] as CallSpy[] };
+    const { db, chains } = asDb([undefined, undefined]);
+    const model = new ZediChatModel({
+      provider: "anthropic",
+      apiKey: "byok-key",
+      apiModelId: "claude-test",
+      modelRowId: "model-2",
+      inputCostUnits: 20,
+      outputCostUnits: 60,
+      userId: "u",
+      tier: "pro",
+      db,
+      feature: "wiki_compose:byok",
+      apiMode: "user_key",
+      callProvider: async (provider, apiKey, model, messages, options = {}) => {
+        spy.calls.push({ provider, apiKey, model, messages, options });
+        return {
+          content: "ok",
+          usage: { inputTokens: 0, outputTokens: 0 },
+          finishReason: "stop",
+        };
+      },
+      streamProvider: async function* () {},
+    });
+    void db;
+
+    await model.invoke([new HumanMessage("hi")]);
+
+    const valuesArg = chains[0]?.ops.find((op) => op.method === "values")?.args[0] as
+      | Record
+      | undefined;
+    expect(valuesArg?.apiMode).toBe("user_key");
+  });
+});
+
+describe("ZediChatModel._streamResponseChunks", () => {
+  it("streams provider chunks and records usage with chars/4 fallback", async () => {
+    const { db, chains } = asDb([undefined, undefined]);
+    const model = new ZediChatModel({
+      provider: "google",
+      apiKey: "k",
+      apiModelId: "gemini-test",
+      modelRowId: "model-3",
+      inputCostUnits: 1,
+      outputCostUnits: 2,
+      userId: "user-x",
+      tier: "free",
+      db,
+      feature: "wiki_compose:stream",
+      callProvider: async () => ({
+        content: "",
+        usage: { inputTokens: 0, outputTokens: 0 },
+        finishReason: "stop",
+      }),
+      streamProvider: async function* () {
+        yield { content: "Hello, " };
+        yield { content: "world!" };
+        yield { done: true, finishReason: "stop" };
+      },
+    });
+
+    const stream = await model.stream([new HumanMessage("Tell me a story")]);
+    const chunks: string[] = [];
+    for await (const chunk of stream) {
+      chunks.push(typeof chunk.content === "string" ? chunk.content : "");
+    }
+
+    // Provider emitted two text chunks → those surface to the caller plus a
+    // final "" chunk that carries aggregated usage_metadata.
+    // プロバイダの 2 件のテキストチャンクが届き、最後に空 content + usage チャンクが届く。
+    expect(chunks).toEqual(["Hello, ", "world!", ""]);
+
+    // Usage was recorded with the chars/4 estimator.
+    // chars/4 推定で usage 記録が走る。
+    expect(chains.length).toBe(2);
+    const valuesArg = chains[0]?.ops.find((op) => op.method === "values")?.args[0] as
+      | Record
+      | undefined;
+
+    // prompt: "Tell me a story" = 15 chars → ceil(15/4) = 4
+    // response: "Hello, world!" = 13 chars → ceil(13/4) = 4
+    expect(valuesArg?.inputTokens).toBe(4);
+    expect(valuesArg?.outputTokens).toBe(4);
+    // (4/1000)*1 + (4/1000)*2 = 0.012 → ceil → 1
+    expect(valuesArg?.costUnits).toBe(1);
+  });
+
+  it("uses 'incomplete' finishReason when the provider stream ends without done=true", async () => {
+    const { db } = asDb([undefined, undefined]);
+    const model = new ZediChatModel({
+      provider: "openai",
+      apiKey: "k",
+      apiModelId: "m",
+      modelRowId: "m",
+      inputCostUnits: 0,
+      outputCostUnits: 0,
+      userId: "u",
+      tier: "free",
+      db,
+      feature: "x",
+      streamProvider: async function* () {
+        yield { content: "partial" };
+        // No done chunk before generator returns.
+      },
+    });
+
+    const lastChunks: unknown[] = [];
+    const stream = await model.stream([new HumanMessage("hi")]);
+    for await (const chunk of stream) lastChunks.push(chunk);
+    const last = lastChunks[lastChunks.length - 1] as {
+      response_metadata?: { finishReason?: string };
+    };
+    expect(last.response_metadata?.finishReason).toBe("incomplete");
+  });
+});
+
+describe("ZediChatModel._llmType", () => {
+  it("identifies the model family as 'zedi-chat'", () => {
+    const spy = { calls: [] as CallSpy[] };
+    const { model } = buildModel(
+      { content: "", usage: { inputTokens: 0, outputTokens: 0 }, finishReason: "stop" },
+      spy,
+    );
+    expect(model._llmType()).toBe("zedi-chat");
+  });
+});
diff --git a/server/api/src/__tests__/agents/core/tools/tools.test.ts b/server/api/src/__tests__/agents/core/tools/tools.test.ts
new file mode 100644
index 00000000..d857467b
--- /dev/null
+++ b/server/api/src/__tests__/agents/core/tools/tools.test.ts
@@ -0,0 +1,100 @@
+/**
+ * Tools (web_search / wiki_search / fetch_article / image_search) のスキーマと
+ * `bindTools` 互換性を確認するテスト。本実装は #949 以降だが、スキーマ・名前が
+ * P0 段階で固まっていることをテストで担保する。
+ *
+ * Pin the public surface of the shared tool set so P1+ subgraph PRs cannot
+ * silently rename or restructure a tool. Behaviour itself is stubbed and not
+ * asserted here beyond "returns the sentinel string".
+ */
+import { describe, expect, it } from "vitest";
+import {
+  fetchArticleInputSchema,
+  fetchArticleTool,
+  FETCH_ARTICLE_TOOL_NAME,
+  imageSearchInputSchema,
+  imageSearchTool,
+  IMAGE_SEARCH_TOOL_NAME,
+  SHARED_TOOLS,
+  webSearchInputSchema,
+  webSearchTool,
+  WEB_SEARCH_TOOL_NAME,
+  wikiSearchInputSchema,
+  wikiSearchTool,
+  WIKI_SEARCH_TOOL_NAME,
+} from "../../../../agents/core/tools/index.js";
+
+describe("tool names", () => {
+  it("are stable and unique across the shared set", () => {
+    const names = [
+      WEB_SEARCH_TOOL_NAME,
+      WIKI_SEARCH_TOOL_NAME,
+      FETCH_ARTICLE_TOOL_NAME,
+      IMAGE_SEARCH_TOOL_NAME,
+    ];
+    expect(new Set(names).size).toBe(names.length);
+    expect(WEB_SEARCH_TOOL_NAME).toBe("web_search");
+    expect(WIKI_SEARCH_TOOL_NAME).toBe("wiki_search");
+    expect(FETCH_ARTICLE_TOOL_NAME).toBe("fetch_article");
+    expect(IMAGE_SEARCH_TOOL_NAME).toBe("image_search");
+  });
+});
+
+describe("input schemas", () => {
+  it("web_search requires a non-empty query", () => {
+    expect(webSearchInputSchema.safeParse({ query: "" }).success).toBe(false);
+    expect(webSearchInputSchema.safeParse({ query: "ripgrep" }).success).toBe(true);
+  });
+  it("web_search rejects limit > 10", () => {
+    expect(webSearchInputSchema.safeParse({ query: "x", limit: 11 }).success).toBe(false);
+  });
+  it("wiki_search rejects limit > 20", () => {
+    expect(wikiSearchInputSchema.safeParse({ query: "x", limit: 21 }).success).toBe(false);
+  });
+  it("fetch_article rejects non-http URLs", () => {
+    expect(fetchArticleInputSchema.safeParse({ url: "ftp://x/y" }).success).toBe(false);
+    expect(fetchArticleInputSchema.safeParse({ url: "https://x/y" }).success).toBe(true);
+  });
+  it("fetch_article clamps previewLength to 500..8000", () => {
+    expect(
+      fetchArticleInputSchema.safeParse({ url: "https://x", previewLength: 100 }).success,
+    ).toBe(false);
+    expect(
+      fetchArticleInputSchema.safeParse({ url: "https://x", previewLength: 4000 }).success,
+    ).toBe(true);
+  });
+  it("image_search rejects page > 10", () => {
+    expect(imageSearchInputSchema.safeParse({ query: "x", page: 11 }).success).toBe(false);
+  });
+});
+
+describe("SHARED_TOOLS", () => {
+  it("contains all four shared tools in a stable order", () => {
+    expect(SHARED_TOOLS.map((t) => t.name)).toEqual([
+      WEB_SEARCH_TOOL_NAME,
+      WIKI_SEARCH_TOOL_NAME,
+      FETCH_ARTICLE_TOOL_NAME,
+      IMAGE_SEARCH_TOOL_NAME,
+    ]);
+  });
+});
+
+describe("stub tool bodies", () => {
+  it("web_search returns the not-implemented sentinel", async () => {
+    const out = (await webSearchTool.invoke({ query: "ripgrep" })) as unknown;
+    expect(typeof out).toBe("string");
+    expect(out).toMatch(/WEB_SEARCH_NOT_IMPLEMENTED/);
+  });
+  it("wiki_search returns the not-implemented sentinel", async () => {
+    const out = (await wikiSearchTool.invoke({ query: "ripgrep" })) as unknown;
+    expect(out).toMatch(/WIKI_SEARCH_NOT_IMPLEMENTED/);
+  });
+  it("fetch_article returns the not-implemented sentinel", async () => {
+    const out = (await fetchArticleTool.invoke({ url: "https://example.com" })) as unknown;
+    expect(out).toMatch(/FETCH_ARTICLE_NOT_IMPLEMENTED/);
+  });
+  it("image_search returns the not-implemented sentinel", async () => {
+    const out = (await imageSearchTool.invoke({ query: "cat" })) as unknown;
+    expect(out).toMatch(/IMAGE_SEARCH_NOT_IMPLEMENTED/);
+  });
+});
diff --git a/server/api/src/__tests__/agents/runner/graphRunner.test.ts b/server/api/src/__tests__/agents/runner/graphRunner.test.ts
new file mode 100644
index 00000000..9eeef85c
--- /dev/null
+++ b/server/api/src/__tests__/agents/runner/graphRunner.test.ts
@@ -0,0 +1,180 @@
+/**
+ * GraphRunner のテスト。registry にスタブ graph を登録した状態で invoke /
+ * streamEvents が registry を介して動くことを確認する。実 LangGraph を起動して
+ * `END` ノードまで走らせるため、ここではモック graph ではなく `stubGraph` を使う。
+ *
+ * Tests for {@link GraphRunner}: registry resolution, invoke happy path,
+ * streamEvents iteration, and resume payload shape. Uses the real
+ * `wiki-compose-stub` graph (no external IO) instead of a hand-rolled mock so
+ * the test stays close to production runtime behaviour.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { GraphRunner } from "../../../agents/runner/graphRunner.js";
+import {
+  GraphNotRegisteredError,
+  __resetRegistryForTests,
+  registerGraph,
+} from "../../../agents/registry/graphRegistry.js";
+import { STUB_GRAPH_ID, registerStubGraph } from "../../../agents/registry/stubGraph.js";
+import type { GraphContext } from "../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../types/index.js";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "thread-1",
+    sessionId: "thread-1",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: STUB_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "test",
+  };
+}
+
+describe("GraphRunner.invoke", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerStubGraph();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("executes the stub graph end-to-end and marks the run completed", async () => {
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: STUB_GRAPH_ID,
+        context: fakeContext(),
+        checkpointer: false,
+      },
+      { kind: "input", value: { messages: [] } },
+    );
+
+    expect(result.status).toBe("completed");
+    // The stub graph sets `phase` to "completed" in its single node.
+    // スタブグラフは noop ノードで phase を completed にする。
+    expect((result.output as { phase?: string })?.phase).toBe("completed");
+  });
+
+  it("throws GraphNotRegisteredError for an unknown graphId", async () => {
+    const runner = new GraphRunner();
+    await expect(
+      runner.invoke(
+        { graphId: "does-not-exist", context: fakeContext(), checkpointer: false },
+        { kind: "input", value: {} },
+      ),
+    ).rejects.toBeInstanceOf(GraphNotRegisteredError);
+  });
+
+  it("passes thread_id and the zedi graph context through configurable", async () => {
+    let capturedConfig: unknown;
+    registerGraph({
+      id: "spy-graph",
+      version: "0.0.0",
+      phase: "spy",
+      description: "captures the runnable config",
+      factory: () => ({
+        async invoke(_input: unknown, options: unknown) {
+          capturedConfig = options;
+          return { ok: true };
+        },
+        async stream() {
+          throw new Error("not used");
+        },
+        streamEvents() {
+          throw new Error("not used");
+        },
+      }),
+    });
+
+    const runner = new GraphRunner();
+    await runner.invoke(
+      { graphId: "spy-graph", context: fakeContext(), checkpointer: false },
+      { kind: "input", value: {} },
+    );
+
+    const cfg = capturedConfig as {
+      configurable: Record;
+      recursionLimit: number;
+    };
+    expect(cfg.configurable.thread_id).toBe("thread-1");
+    expect(cfg.configurable.zediGraphContext).toMatchObject({
+      threadId: "thread-1",
+      userId: "user-1",
+      pageId: "page-1",
+    });
+    expect(cfg.recursionLimit).toBe(25);
+  });
+});
+
+describe("GraphRunner.streamEvents", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerStubGraph();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("returns an async iterable that emits at least one event", async () => {
+    const runner = new GraphRunner();
+    const events = runner.streamEvents(
+      { graphId: STUB_GRAPH_ID, context: fakeContext(), checkpointer: false },
+      { kind: "input", value: { messages: [] } },
+    );
+
+    const collected: unknown[] = [];
+    for await (const ev of events) {
+      collected.push(ev);
+    }
+    // The stub graph is small but always produces multiple lifecycle events
+    // (chain_start / chain_end at minimum). We only assert non-empty so the
+    // test is robust against LangGraph version changes.
+    // LangGraph のバージョン差を吸収するため、件数だけ確認する。
+    expect(collected.length).toBeGreaterThan(0);
+  });
+});
+
+describe("GraphRunner.resume", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("invokes the graph with a Command({ resume }) payload", async () => {
+    let captured: unknown;
+    registerGraph({
+      id: "resume-spy",
+      version: "0.0.0",
+      phase: "spy",
+      description: "captures resume payloads",
+      factory: () => ({
+        async invoke(input: unknown) {
+          captured = input;
+          return {};
+        },
+        async stream() {
+          throw new Error("not used");
+        },
+        streamEvents() {
+          throw new Error("not used");
+        },
+      }),
+    });
+
+    const runner = new GraphRunner();
+    await runner.resume(
+      { graphId: "resume-spy", context: fakeContext(), checkpointer: false },
+      { answer: "yes" },
+    );
+
+    expect(captured).toBeDefined();
+    // LangGraph `Command` carries a `resume` field that holds the user payload.
+    expect((captured as { resume?: unknown }).resume).toEqual({ answer: "yes" });
+  });
+});
diff --git a/server/api/src/__tests__/agents/runner/sseMapper.test.ts b/server/api/src/__tests__/agents/runner/sseMapper.test.ts
new file mode 100644
index 00000000..ed6d6170
--- /dev/null
+++ b/server/api/src/__tests__/agents/runner/sseMapper.test.ts
@@ -0,0 +1,130 @@
+/**
+ * sseMapper のテスト。LangGraph 風イベントから `SseEvent` への変換を確認する。
+ *
+ * Pure-function tests for {@link mapLangGraphEvent} and the small builder
+ * helpers. The mapper is the sole place that translates LangGraph's runtime
+ * event shape into wire SSE; pinning it here keeps the wire contract stable.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  doneEvent,
+  errorEvent,
+  mapLangGraphEvent,
+  startedEvent,
+  statusEvent,
+  usageEvent,
+  type LangGraphRuntimeEvent,
+} from "../../../agents/runner/sseMapper.js";
+
+describe("startedEvent / statusEvent / usageEvent / doneEvent / errorEvent", () => {
+  it("startedEvent omits phase when not provided", () => {
+    expect(startedEvent("s1", "g1")).toEqual({
+      type: "started",
+      sessionId: "s1",
+      graphId: "g1",
+    });
+  });
+
+  it("startedEvent includes phase when provided", () => {
+    expect(startedEvent("s1", "g1", "init")).toEqual({
+      type: "started",
+      sessionId: "s1",
+      graphId: "g1",
+      phase: "init",
+    });
+  });
+
+  it("statusEvent passes through message", () => {
+    expect(statusEvent("draft", "writing")).toEqual({
+      type: "status",
+      phase: "draft",
+      message: "writing",
+    });
+  });
+
+  it("usageEvent forwards all numeric fields", () => {
+    expect(usageEvent({ inputTokens: 1, outputTokens: 2, costUnits: 3, usagePercent: 4 })).toEqual({
+      type: "usage",
+      inputTokens: 1,
+      outputTokens: 2,
+      costUnits: 3,
+      usagePercent: 4,
+    });
+  });
+
+  it("doneEvent forwards status", () => {
+    expect(doneEvent("interrupted")).toEqual({ type: "done", status: "interrupted" });
+  });
+
+  it("errorEvent forwards retryable flag", () => {
+    expect(errorEvent("boom", true)).toEqual({
+      type: "error",
+      message: "boom",
+      retryable: true,
+    });
+  });
+});
+
+describe("mapLangGraphEvent", () => {
+  it("maps on_chat_model_stream to a token event with node name", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_chat_model_stream",
+      data: { chunk: { content: "Hello" } },
+      metadata: { langgraph_node: "draft" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([{ type: "token", node: "draft", content: "Hello" }]);
+  });
+
+  it("drops empty chat model stream chunks", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_chat_model_stream",
+      data: { chunk: { content: "" } },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([]);
+  });
+
+  it("maps on_tool_start to a tool_start event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_tool_start",
+      name: "web_search",
+      data: { input: { query: "ripgrep" } },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "tool_start", tool: "web_search", input: { query: "ripgrep" } },
+    ]);
+  });
+
+  it("maps on_tool_end with output length", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_tool_end",
+      name: "web_search",
+      data: { output: "result text" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "tool_end", tool: "web_search", outputLength: "result text".length },
+    ]);
+  });
+
+  it("maps on_tool_end with error string", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_tool_end",
+      name: "fetch_article",
+      data: { error: "blocked" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "tool_end", tool: "fetch_article", error: "blocked" },
+    ]);
+  });
+
+  it("maps on_chain_end with phase to a status event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_chain_end",
+      data: { output: { phase: "completed" } },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([{ type: "status", phase: "completed" }]);
+  });
+
+  it("returns an empty array for unrecognised events", () => {
+    expect(mapLangGraphEvent({ event: "on_unknown_event" })).toEqual([]);
+  });
+});
diff --git a/server/api/src/__tests__/routes/composeSessions.test.ts b/server/api/src/__tests__/routes/composeSessions.test.ts
new file mode 100644
index 00000000..cf67f5d7
--- /dev/null
+++ b/server/api/src/__tests__/routes/composeSessions.test.ts
@@ -0,0 +1,265 @@
+/**
+ * composeSessions ルートのテスト（認可・CRUD・backend ガード）。
+ *
+ * Tests for `/api/pages/:pageId/compose-sessions[/:id]`. Focuses on the parts
+ * that have to be right before a real graph is wired up: input validation,
+ * page access enforcement (issue #823 note-role only), DB row shape, and the
+ * backend whitelist.
+ *
+ * `run` / `resume` の SSE 経路は LangGraph 実体に依存するため、本テストでは
+ * CRUD と 4xx パスに絞っている。SSE の整合性は `sseMapper` 単体テストと
+ * `graphRunner` 単体テストでカバー済み。
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { Context, Next } from "hono";
+import type { AppEnv } from "../../types/index.js";
+
+vi.mock("../../middleware/auth.js", () => ({
+  authRequired: async (c: Context, next: Next) => {
+    const userId = c.req.header("x-test-user-id");
+    if (!userId) return c.json({ message: "Unauthorized" }, 401);
+    c.set("userId", userId);
+    await next();
+  },
+}));
+
+vi.mock("../../middleware/rateLimit.js", () => ({
+  rateLimit: () => async (_c: Context, next: Next) => {
+    await next();
+  },
+}));
+
+import { Hono } from "hono";
+import composeSessionRoutes from "../../routes/composeSessions.js";
+import { errorHandler } from "../../middleware/errorHandler.js";
+import { createMockDb } from "../createMockDb.js";
+import { __resetRegistryForTests, registerGraph } from "../../agents/registry/graphRegistry.js";
+
+const OWNER_ID = "owner-1";
+const PAGE_ID = "page-1";
+const NOTE_ID = "note-1";
+const GRAPH_ID = "test-graph";
+
+function authHeaders(userId: string = OWNER_ID) {
+  return {
+    "x-test-user-id": userId,
+    "Content-Type": "application/json",
+  };
+}
+
+function mockNote() {
+  return {
+    id: NOTE_ID,
+    ownerId: OWNER_ID,
+    title: "n",
+    visibility: "private" as const,
+    editPermission: "owner_only" as const,
+    isOfficial: false,
+    viewCount: 0,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    isDeleted: false,
+  };
+}
+
+/**
+ * assertPageEditAccess の SELECT 並び:
+ *   1: pages row, 2: caller email, 3: findActiveNoteById.
+ * assertPageViewAccess も同じ並びだが、editPermission のチェックが追加で発生する。
+ */
+function pageAccessPrefix() {
+  return [
+    [{ id: PAGE_ID, ownerId: OWNER_ID, noteId: NOTE_ID }],
+    [{ email: "owner@example.com" }],
+    [mockNote()],
+  ];
+}
+
+function createComposeApp(dbResults: unknown[]) {
+  const { db, chains } = createMockDb(dbResults);
+  const app = new Hono();
+  app.use("*", async (c, next) => {
+    c.set("db", db as unknown as AppEnv["Variables"]["db"]);
+    await next();
+  });
+  app.onError(errorHandler);
+  app.route("/api/pages", composeSessionRoutes);
+  return { app, chains };
+}
+
+beforeEach(() => {
+  __resetRegistryForTests();
+  // Register a graph the routes can resolve. Body is irrelevant for CRUD tests.
+  registerGraph({
+    id: GRAPH_ID,
+    version: "0.0.0",
+    phase: "test",
+    description: "test graph",
+    factory: () => ({
+      invoke: async () => ({}),
+      stream: async () => undefined,
+      streamEvents: () => undefined,
+    }),
+  });
+});
+
+describe("POST /api/pages/:pageId/compose-sessions", () => {
+  it("rejects requests without auth", async () => {
+    const { app } = createComposeApp([]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ graphId: GRAPH_ID }),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it("returns 400 when graphId is missing", async () => {
+    const { app } = createComposeApp([
+      ...pageAccessPrefix(),
+      // No further DB chains; route fails before insert.
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("returns 400 when graphId is unknown", async () => {
+    const { app } = createComposeApp([...pageAccessPrefix()]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ graphId: "never-registered" }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("returns 400 for unsupported backend (BYOK forward-compat)", async () => {
+    const { app } = createComposeApp([...pageAccessPrefix()]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ graphId: GRAPH_ID, backend: "byok" }),
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it("creates a session row with the resolved backend defaulting to zedi_managed", async () => {
+    const createdRow = {
+      id: "sess-1",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: GRAPH_ID,
+      phase: "init",
+      backend: "zedi_managed",
+      status: "pending",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [createdRow], // insert().values().returning()
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions`, {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify({ graphId: GRAPH_ID }),
+    });
+    expect(res.status).toBe(201);
+    const body = (await res.json()) as { session: { id: string; backend: string } };
+    expect(body.session.id).toBe("sess-1");
+    expect(body.session.backend).toBe("zedi_managed");
+    // 4 DB chains: 3 access checks + 1 insert.
+    expect(chains.length).toBe(4);
+    expect(chains[3]?.startMethod).toBe("insert");
+  });
+});
+
+describe("GET /api/pages/:pageId/compose-sessions/:id", () => {
+  it("returns 404 when the session row is not found", async () => {
+    const { app } = createComposeApp([
+      ...pageAccessPrefix(),
+      [], // select() returning no rows
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/missing`, {
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  it("returns the session row when found", async () => {
+    const row = {
+      id: "sess-2",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: GRAPH_ID,
+      phase: "init",
+      backend: "zedi_managed",
+      status: "pending",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app } = createComposeApp([...pageAccessPrefix(), [row]]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/sess-2`, {
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { session: { id: string } };
+    expect(body.session.id).toBe("sess-2");
+  });
+});
+
+describe("DELETE /api/pages/:pageId/compose-sessions/:id", () => {
+  it("returns 404 when the session does not exist", async () => {
+    const { app } = createComposeApp([...pageAccessPrefix(), []]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/none`, {
+      method: "DELETE",
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  it("is a no-op when the session is already completed", async () => {
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [{ id: "sess-x", status: "completed" }],
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/sess-x`, {
+      method: "DELETE",
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { status: string };
+    expect(body.status).toBe("completed");
+    // 4 chains: 3 page-access + 1 select. No update chain triggered.
+    expect(chains.filter((c) => c.startMethod === "update").length).toBe(0);
+  });
+
+  it("cancels an active session", async () => {
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [{ id: "sess-y", status: "running" }],
+      undefined, // update chain
+    ]);
+    const res = await app.request(`/api/pages/${PAGE_ID}/compose-sessions/sess-y`, {
+      method: "DELETE",
+      headers: authHeaders(),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { status: string };
+    expect(body.status).toBe("cancelled");
+    // Update chain set status to "cancelled".
+    const updateChain = chains.find((c) => c.startMethod === "update");
+    const setOp = updateChain?.ops.find((op) => op.method === "set");
+    expect((setOp?.args[0] as { status?: string })?.status).toBe("cancelled");
+  });
+});
diff --git a/server/api/src/agents/core/checkpoint/index.ts b/server/api/src/agents/core/checkpoint/index.ts
new file mode 100644
index 00000000..6bd832e0
--- /dev/null
+++ b/server/api/src/agents/core/checkpoint/index.ts
@@ -0,0 +1,41 @@
+/**
+ * Resolve a LangGraph checkpointer for a compose-session run.
+ *
+ * P0 でルートが checkpointer を取得する際の単一入口。本番 (Railway) では
+ * `DATABASE_URL` / `POSTGRES_URL` が必ず設定されているため `PostgresSaver` を
+ * 返し、テストや CI のように DB 接続情報が無い環境では `false` を返して
+ * LangGraph の checkpoint 機構を無効化する。
+ *
+ * Returns either the process-wide `PostgresSaver` (when a DATABASE_URL is
+ * available) or `false`. The route layer passes the result through to
+ * `GraphRunner`, which forwards it to `StateGraph.compile({ checkpointer })`.
+ * `false` keeps tests and the smoke-test path runnable without DDL.
+ *
+ * Issue: otomatty/zedi#948
+ */
+import type { BaseCheckpointSaver } from "@langchain/langgraph";
+import {
+  ensurePostgresCheckpointerSetup,
+  getPostgresCheckpointer,
+} from "./postgresCheckpointer.js";
+
+/**
+ * `DATABASE_URL` または `POSTGRES_URL` が設定されているなら `PostgresSaver` を
+ * 返し、`setup()` をプロセス内で 1 度だけ実行する。未設定なら `false`。
+ *
+ * Returns the singleton `PostgresSaver` when a DB connection string is
+ * available (and ensures `setup()` has run); otherwise returns `false` to opt
+ * out of checkpointing.
+ */
+export async function resolveCheckpointerForRun(): Promise {
+  if (!process.env.DATABASE_URL && !process.env.POSTGRES_URL) {
+    return false;
+  }
+  await ensurePostgresCheckpointerSetup();
+  return getPostgresCheckpointer();
+}
+
+export {
+  ensurePostgresCheckpointerSetup,
+  getPostgresCheckpointer,
+} from "./postgresCheckpointer.js";
diff --git a/server/api/src/agents/core/checkpoint/postgresCheckpointer.ts b/server/api/src/agents/core/checkpoint/postgresCheckpointer.ts
new file mode 100644
index 00000000..fd4ce022
--- /dev/null
+++ b/server/api/src/agents/core/checkpoint/postgresCheckpointer.ts
@@ -0,0 +1,75 @@
+/**
+ * `PostgresSaver` wrapper for the Wiki Compose graph runtime.
+ *
+ * LangGraph 公式の `PostgresSaver` を Zedi が使う 1 つの connection string に
+ * 束ねるだけの薄いラッパー。`checkpoints` / `checkpoint_blobs` / `checkpoint_writes`
+ * の 3 テーブルは `setup()` が動的に作る (U4 で別管理)。本ラッパーは
+ * `DATABASE_URL` または `POSTGRES_URL` から接続文字列を取得し、プロセスローカル
+ * にシングルトンを保持する。
+ *
+ * Singleton wrapper around LangGraph's `PostgresSaver`. The saver owns its own
+ * `checkpoints*` tables — they are created by `setup()` and intentionally are
+ * NOT part of Drizzle's migration set, so Drizzle never tries to diff them.
+ */
+import { PostgresSaver } from "@langchain/langgraph-checkpoint-postgres";
+
+let cached: PostgresSaver | null = null;
+let setupOnce: Promise | null = null;
+
+/**
+ * `DATABASE_URL` (preferred) or `POSTGRES_URL` を返す。両方未設定なら例外。
+ *
+ * Return the Postgres connection string used by the rest of the API. Throws
+ * when neither variable is set so misconfigured deployments fail loudly
+ * instead of silently writing to an in-memory store.
+ */
+function readConnectionString(): string {
+  const value = process.env.DATABASE_URL ?? process.env.POSTGRES_URL;
+  if (!value || !value.trim()) {
+    throw new Error("DATABASE_URL or POSTGRES_URL must be set to use PostgresSaver");
+  }
+  return value;
+}
+
+/**
+ * `PostgresSaver` を `(プロセス, schema)` 単位でシングルトン化する。
+ *
+ * Returns a process-wide singleton `PostgresSaver`. `setup()` is intentionally
+ * NOT awaited here — callers that need DDL applied should call
+ * {@link ensurePostgresCheckpointerSetup} once at boot. Keeping creation
+ * separate from setup means tests can construct the saver without touching the
+ * database.
+ *
+ * @param schema  Postgres schema for checkpoint tables (default "public").
+ */
+export function getPostgresCheckpointer(schema: string = "public"): PostgresSaver {
+  if (cached) return cached;
+  cached = PostgresSaver.fromConnString(readConnectionString(), { schema });
+  return cached;
+}
+
+/**
+ * `PostgresSaver.setup()` をプロセス内で 1 度だけ実行する。複数の compose
+ * セッションが並行起動しても DDL は 1 回しか走らない。
+ *
+ * Idempotent `setup()` runner. Subsequent calls return the cached promise so
+ * concurrent compose-session starts do not race to create the checkpoint
+ * tables.
+ */
+export async function ensurePostgresCheckpointerSetup(schema: string = "public"): Promise {
+  if (!setupOnce) {
+    const saver = getPostgresCheckpointer(schema);
+    setupOnce = saver.setup();
+  }
+  return setupOnce;
+}
+
+/**
+ * テスト用にキャッシュを破棄する。本番コードからは呼ばない。
+ *
+ * Drops the cached singleton. Test-only.
+ */
+export function __resetPostgresCheckpointerForTests(): void {
+  cached = null;
+  setupOnce = null;
+}
diff --git a/server/api/src/agents/core/llm/modelFactory.ts b/server/api/src/agents/core/llm/modelFactory.ts
new file mode 100644
index 00000000..7aa88c8e
--- /dev/null
+++ b/server/api/src/agents/core/llm/modelFactory.ts
@@ -0,0 +1,145 @@
+/**
+ * Build a {@link ZediChatModel} for a Wiki Compose run.
+ *
+ * 1 つの compose セッションぶんの `ZediChatModel` を組み立てるファクトリ。
+ * `validateModelAccess` で tier ゲートと cost 単価を解決し、`process.env` から
+ * provider API キーを引いて `ZediChatModel` に注入する。BYOK (#951) で
+ * `backend === "byok"` が来た場合の経路もこのファクトリで分岐する想定。
+ *
+ * Resolves model access (tier check + cost units) and provider credentials,
+ * then constructs a `ZediChatModel`. Centralising this lets future BYOK paths
+ * branch in one place instead of every subgraph.
+ */
+import { getProviderApiKeyName } from "../../../services/aiProviders.js";
+import { validateModelAccess } from "../../../services/usageService.js";
+import type { AIProviderType, ApiMode, Database, UserTier } from "../../../types/index.js";
+import {
+  isExecutionBackend,
+  SUPPORTED_BACKENDS_P0,
+  type ExecutionBackend,
+} from "../types/executionBackend.js";
+import { ZediChatModel } from "./zediChatModel.js";
+
+/**
+ * `createZediChatModel` の入力。
+ * Input for {@link createZediChatModel}.
+ *
+ * @property modelId  `ai_models.id`。`validateModelAccess` の入力と同じ。
+ *                    `ai_models.id` (matches `validateModelAccess`).
+ * @property userId   実行ユーザー ID。Executing user id.
+ * @property tier     ユーザー tier。先に `getUserTier` で解決済みのものを渡す。
+ *                    User tier (pre-resolved via `getUserTier`).
+ * @property db       Drizzle DB ハンドル。Drizzle DB handle.
+ * @property feature  `recordUsage` の feature ラベル。`recordUsage` feature label.
+ * @property backend  実行 backend。P0 では `zedi_managed` のみ受理。
+ *                    Execution backend; P0 only accepts `zedi_managed`.
+ * @property apiKey   BYOK 用の上書き API キー（任意）。`backend === "byok"` の時必須。
+ *                    Override API key for BYOK; required when `backend === "byok"`.
+ * @property temperature  Provider オプション。Provider option.
+ * @property maxTokens    Provider オプション。Provider option.
+ */
+export interface CreateZediChatModelInput {
+  modelId: string;
+  userId: string;
+  tier: UserTier;
+  db: Database;
+  feature: string;
+  backend: ExecutionBackend;
+  apiKey?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+/**
+ * 未サポート backend を投げる時のエラー。route 層が 4xx に変換できるよう
+ * 専用クラスにしておく。
+ *
+ * Thrown when a caller hands in a backend that is not yet wired up. Carries a
+ * machine-readable code so the route layer can map to a 4xx without sniffing
+ * the message string.
+ */
+export class UnsupportedBackendError extends Error {
+  /** Machine-readable code. */
+  readonly code = "UNSUPPORTED_BACKEND";
+  /** The backend value that triggered the error. */
+  readonly backend: string;
+  constructor(backend: string) {
+    super(`Execution backend "${backend}" is not supported in P0 (zedi_managed only).`);
+    this.name = "UnsupportedBackendError";
+    this.backend = backend;
+  }
+}
+
+/**
+ * Validate that the requested `backend` is a P0-supported value and return it
+ * narrowed to {@link ExecutionBackend}.
+ *
+ * P0 でサポートされる backend かを検証する。`byok` / `byo_runner` は #951 以降。
+ */
+export function assertSupportedBackendP0(backend: string): ExecutionBackend {
+  if (!isExecutionBackend(backend) || !SUPPORTED_BACKENDS_P0.includes(backend)) {
+    throw new UnsupportedBackendError(backend);
+  }
+  return backend;
+}
+
+/**
+ * Build a {@link ZediChatModel} ready to be plugged into a LangGraph node.
+ * LangGraph ノードへ差し込む `ZediChatModel` を組み立てて返す。
+ *
+ * 1. backend を検証（P0 は `zedi_managed` のみ）。
+ * 2. `validateModelAccess` で tier ゲート + cost 単価を解決。
+ * 3. provider API キーを backend に応じて解決
+ *    （`zedi_managed` → `process.env[apiKeyName]`、`byok` → 入力の `apiKey`）。
+ */
+export async function createZediChatModel(input: CreateZediChatModelInput): Promise {
+  const backend = assertSupportedBackendP0(input.backend);
+
+  const modelInfo = await validateModelAccess(input.modelId, input.tier, input.db);
+  const provider = modelInfo.provider as AIProviderType;
+
+  const apiKey = resolveApiKey(backend, provider, input.apiKey);
+  const apiMode: ApiMode = backend === "byok" ? "user_key" : "system";
+
+  return new ZediChatModel({
+    provider,
+    apiKey,
+    apiModelId: modelInfo.apiModelId,
+    modelRowId: input.modelId,
+    inputCostUnits: modelInfo.inputCostUnits,
+    outputCostUnits: modelInfo.outputCostUnits,
+    userId: input.userId,
+    tier: input.tier,
+    db: input.db,
+    feature: input.feature,
+    apiMode,
+    temperature: input.temperature,
+    maxTokens: input.maxTokens,
+  });
+}
+
+/**
+ * Backend + provider に応じた API キー解決。`zedi_managed` は `process.env` を
+ * 引き、`byok` は呼び出し側からの注入キーを必須にする。
+ *
+ * Resolve the provider API key per backend. `zedi_managed` reads `process.env`;
+ * `byok` requires an explicitly injected key.
+ */
+function resolveApiKey(
+  backend: ExecutionBackend,
+  provider: AIProviderType,
+  overrideKey: string | undefined,
+): string {
+  if (backend === "zedi_managed") {
+    const envName = getProviderApiKeyName(provider);
+    const key = process.env[envName];
+    if (!key) {
+      throw new Error(`API key not configured: ${envName}`);
+    }
+    return key;
+  }
+  if (!overrideKey || !overrideKey.trim()) {
+    throw new Error(`apiKey is required for backend="${backend}"`);
+  }
+  return overrideKey;
+}
diff --git a/server/api/src/agents/core/llm/usageCallback.ts b/server/api/src/agents/core/llm/usageCallback.ts
new file mode 100644
index 00000000..7f6dd808
--- /dev/null
+++ b/server/api/src/agents/core/llm/usageCallback.ts
@@ -0,0 +1,130 @@
+/**
+ * Usage attribution helpers for `ZediChatModel`.
+ *
+ * `ZediChatModel` の usage 記録ヘルパー。LangGraph 経路でもチャットページと
+ * 同じ `recordUsage` + `calculateCost` を通すための薄いアダプタ。BaseChatModel
+ * の callback 機構を使わずに同期的に呼ぶ理由は、(1) graph 側の retry / 再実行で
+ * cost を二重計上したくない、(2) 計算ロジックを単体テストしやすくするため。
+ *
+ * Thin adapter that routes LangGraph LLM usage through the same
+ * `recordUsage` / `calculateCost` path as the chat endpoint. Kept as a plain
+ * function instead of a LangChain callback so it can be unit-tested without
+ * spinning up the callback system and so retries do not double-count.
+ */
+import type { BaseMessage } from "@langchain/core/messages";
+import { calculateCost, recordUsage } from "../../../services/usageService.js";
+import type {
+  AIMessage as ZediAIMessage,
+  ApiMode,
+  Database,
+  TokenUsage,
+} from "../../../types/index.js";
+
+/**
+ * `recordZediUsage` の入力。
+ * Input for {@link recordZediUsage}.
+ *
+ * @property db          Drizzle DB ハンドル。Drizzle DB handle.
+ * @property userId      実行ユーザー ID。Executing user id.
+ * @property modelId     `ai_models.id`。実モデル行 ID（API モデル名ではない）。
+ *                       Database `ai_models.id` (not the provider model name).
+ * @property feature     `ai_usage_logs.feature` のラベル。`recordUsage` feature label.
+ * @property usage       消費したトークン数。Token consumption.
+ * @property inputCostUnits  モデルの input 単価（1k tokens あたり cost_units）。
+ *                            Per-1k input cost in cost units.
+ * @property outputCostUnits モデルの output 単価（1k tokens あたり cost_units）。
+ *                            Per-1k output cost in cost units.
+ * @property apiMode     "system" / "user_key"。BYOK 導入後は "user_key" を渡す。
+ *                       Future-proof flag for BYOK; pass "system" in P0.
+ */
+export interface RecordZediUsageInput {
+  db: Database;
+  userId: string;
+  modelId: string;
+  feature: string;
+  usage: TokenUsage;
+  inputCostUnits: number;
+  outputCostUnits: number;
+  apiMode: ApiMode;
+}
+
+/**
+ * `recordZediUsage` の結果。クライアントに返したり SSE に流したりするのに使う。
+ * Result of {@link recordZediUsage}; suitable to surface via SSE.
+ */
+export interface RecordZediUsageResult {
+  inputTokens: number;
+  outputTokens: number;
+  costUnits: number;
+}
+
+/**
+ * 1 回の LLM 呼び出しぶんの usage を計算して `ai_usage_logs` と `ai_monthly_usage`
+ * に書き込む。LangGraph 経由でも `/api/ai/chat` と同等の課金を成立させる。
+ *
+ * Compute usage cost for a single LLM invocation and persist it via
+ * `recordUsage`. Used by `ZediChatModel` after each provider call.
+ */
+export async function recordZediUsage(input: RecordZediUsageInput): Promise {
+  const costUnits = calculateCost(input.usage, input.inputCostUnits, input.outputCostUnits);
+  await recordUsage(
+    input.userId,
+    input.modelId,
+    input.feature,
+    input.usage,
+    costUnits,
+    input.apiMode,
+    input.db,
+  );
+  return {
+    inputTokens: input.usage.inputTokens,
+    outputTokens: input.usage.outputTokens,
+    costUnits,
+  };
+}
+
+/**
+ * LangChain の `BaseMessage[]` を Zedi の `AIMessage[]` に変換する。
+ * Convert LangChain `BaseMessage[]` to the legacy `AIMessage[]` shape that
+ * `callProvider` / `streamProvider` expect.
+ *
+ * 既存の `aiProviders` 系 API は `role: "user" | "assistant" | "system"` の
+ * 単純な dict 配列を取るため、本関数で type を取り出して文字列化する。Content が
+ * 配列 (multi-modal) の場合は text ブロックのみ連結し、画像等は将来拡張。
+ *
+ * Until the providers gain multi-modal support, this helper concatenates text
+ * blocks from a `BaseMessage` and drops non-text content blocks.
+ */
+export function toZediMessages(messages: BaseMessage[]): ZediAIMessage[] {
+  return messages.map((m) => {
+    const role = messageTypeToRole(m.getType());
+    return { role, content: stringifyContent(m.content) };
+  });
+}
+
+function messageTypeToRole(type: string): ZediAIMessage["role"] {
+  // LangChain message types: "human" | "ai" | "system" | "tool" | "function" | ...
+  // LangChain のメッセージ型を AIProviders が期待する role 文字列に正規化する。
+  if (type === "system") return "system";
+  if (type === "ai") return "assistant";
+  // Treat tool / function / generic / human messages as user-side input to the
+  // model. The providers do not have a richer notion in P0.
+  // tool / function 等は P0 ではユーザー側入力として扱う。
+  return "user";
+}
+
+function stringifyContent(content: BaseMessage["content"]): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (typeof block === "string") {
+      parts.push(block);
+    } else if (block && typeof block === "object" && "type" in block && block.type === "text") {
+      // LangChain content blocks: prefer `.text`; fall back to `.value` if present.
+      const text = (block as { text?: unknown }).text;
+      if (typeof text === "string") parts.push(text);
+    }
+  }
+  return parts.join("");
+}
diff --git a/server/api/src/agents/core/llm/zediChatModel.ts b/server/api/src/agents/core/llm/zediChatModel.ts
new file mode 100644
index 00000000..4defd29b
--- /dev/null
+++ b/server/api/src/agents/core/llm/zediChatModel.ts
@@ -0,0 +1,318 @@
+/**
+ * `ZediChatModel` — LangGraph 経路で使う LangChain `BaseChatModel` 実装。
+ *
+ * `ZediChatModel` is the bridge between LangGraph and Zedi's existing
+ * `aiProviders` + `usageService` stack. Every LLM call inside an agent goes
+ * through this class so that:
+ *
+ * 1. `callProvider` / `streamProvider` (legacy) stays the single network
+ *    boundary to OpenAI / Anthropic / Google; the LangGraph layer never holds
+ *    a provider SDK directly.
+ *    全 LLM 呼び出しは `callProvider` / `streamProvider` を通る。LangGraph 層は
+ *    プロバイダ SDK を直接握らない。
+ *
+ * 2. `validateModelAccess` + `recordUsage` are invoked exactly once per call,
+ *    matching the accounting behaviour of `/api/ai/chat` so monthly budgets
+ *    and feature labels stay consistent.
+ *    `/api/ai/chat` と同じく `validateModelAccess` / `recordUsage` を 1 呼び出し
+ *    あたり 1 回ずつ通す。月次予算と feature ラベルの整合性を保証する。
+ *
+ * 3. P0 (#948) supports backend = `zedi_managed` only. BYOK arrives in #951;
+ *    the constructor accepts an `apiKey` opaquely so the future path can
+ *    inject user-supplied credentials without changing the class shape.
+ *    P0 は backend = `zedi_managed` のみサポート。BYOK は #951 で対応するが、
+ *    本クラスは `apiKey` を不透明に受け取る形にして将来差し替え可能にしてある。
+ *
+ * Note on streaming: `_streamResponseChunks` reuses `streamProvider` and
+ * accumulates tokens locally. Usage is recorded after the stream ends with the
+ * cheap `chars/4` token estimator, identical to `routes/ai/chat.ts`. The estimate
+ * is intentionally not pre-billed before the call — we charge on the way out.
+ *
+ * @see {@link callProvider} / {@link streamProvider}
+ * @see https://github.com/otomatty/zedi/issues/948
+ */
+import {
+  BaseChatModel,
+  type BaseChatModelCallOptions,
+  type BaseChatModelParams,
+} from "@langchain/core/language_models/chat_models";
+import type { CallbackManagerForLLMRun } from "@langchain/core/callbacks/manager";
+import type { BaseMessage } from "@langchain/core/messages";
+import { AIMessage, AIMessageChunk } from "@langchain/core/messages";
+import { ChatGenerationChunk, type ChatResult } from "@langchain/core/outputs";
+import { callProvider, streamProvider } from "../../../services/aiProviders.js";
+import type { AIProviderType, ApiMode, Database, UserTier } from "../../../types/index.js";
+import { recordZediUsage, toZediMessages } from "./usageCallback.js";
+
+/**
+ * `callProvider` / `streamProvider` のインジェクション型。テストでは fake を
+ * 渡し、本番では `aiProviders` から取得した関数をそのまま渡す。
+ *
+ * Pluggable provider callers; tests inject fakes, production wires the real
+ * `callProvider` / `streamProvider`.
+ */
+export interface CallProviderFn {
+  (...args: Parameters): ReturnType;
+}
+export interface StreamProviderFn {
+  (...args: Parameters): ReturnType;
+}
+
+/**
+ * `ZediChatModel` を構築するためのパラメータ。
+ * Constructor input for {@link ZediChatModel}.
+ *
+ * @property provider          AIProviderType。OpenAI / Anthropic / Google.
+ * @property apiKey            プロバイダ向け API キー。P0 では `zedi_managed` 鍵が入る。
+ *                             Provider API key (zedi_managed in P0, BYOK in #951).
+ * @property apiModelId        プロバイダ側モデル ID（例: `gpt-4o-mini`）。
+ *                             Provider model id (`ai_models.modelId`).
+ * @property modelRowId        DB 上の `ai_models.id`。`recordUsage` で使う。
+ *                             `ai_models.id` (DB row id) used by `recordUsage`.
+ * @property inputCostUnits    入力 1k tokens あたりの cost units。
+ *                             Input cost units per 1k tokens.
+ * @property outputCostUnits   出力 1k tokens あたりの cost units。
+ *                             Output cost units per 1k tokens.
+ * @property userId            実行ユーザー ID。Executing user id.
+ * @property tier              ユーザー tier（参照用。validate 済みの想定）。User tier (already validated).
+ * @property db                Drizzle DB ハンドル。Drizzle DB handle.
+ * @property feature           `recordUsage` の feature ラベル。`recordUsage` feature label.
+ * @property apiMode           "system" / "user_key"。P0 では "system"。BYOK 時に切替。
+ * @property callProvider      `callProvider` の差し替え（任意）。Optional override.
+ * @property streamProvider    `streamProvider` の差し替え（任意）。Optional override.
+ */
+export interface ZediChatModelParams extends BaseChatModelParams {
+  provider: AIProviderType;
+  apiKey: string;
+  apiModelId: string;
+  modelRowId: string;
+  inputCostUnits: number;
+  outputCostUnits: number;
+  userId: string;
+  tier: UserTier;
+  db: Database;
+  feature: string;
+  apiMode?: ApiMode;
+  callProvider?: CallProviderFn;
+  streamProvider?: StreamProviderFn;
+  /** モデル呼び出しオプション。temperature / maxTokens 等。Provider options. */
+  temperature?: number;
+  maxTokens?: number;
+}
+
+/**
+ * Concrete `BaseChatModel` implementation routing through Zedi providers.
+ * Zedi の providers 経由で呼び出す `BaseChatModel` 実装。
+ */
+export class ZediChatModel extends BaseChatModel {
+  /** LangChain serialization namespace. LangChain シリアライズ識別子。 */
+  static lc_name(): string {
+    return "ZediChatModel";
+  }
+
+  private readonly provider: AIProviderType;
+  private readonly apiKey: string;
+  private readonly apiModelId: string;
+  private readonly modelRowId: string;
+  private readonly inputCostUnits: number;
+  private readonly outputCostUnits: number;
+  private readonly userId: string;
+  private readonly tier: UserTier;
+  private readonly db: Database;
+  private readonly feature: string;
+  private readonly apiMode: ApiMode;
+  private readonly callProviderFn: CallProviderFn;
+  private readonly streamProviderFn: StreamProviderFn;
+  private readonly temperature?: number;
+  private readonly maxTokens?: number;
+
+  constructor(fields: ZediChatModelParams) {
+    super(fields);
+    this.provider = fields.provider;
+    this.apiKey = fields.apiKey;
+    this.apiModelId = fields.apiModelId;
+    this.modelRowId = fields.modelRowId;
+    this.inputCostUnits = fields.inputCostUnits;
+    this.outputCostUnits = fields.outputCostUnits;
+    this.userId = fields.userId;
+    this.tier = fields.tier;
+    this.db = fields.db;
+    this.feature = fields.feature;
+    this.apiMode = fields.apiMode ?? "system";
+    this.callProviderFn = fields.callProvider ?? callProvider;
+    this.streamProviderFn = fields.streamProvider ?? streamProvider;
+    this.temperature = fields.temperature;
+    this.maxTokens = fields.maxTokens;
+  }
+
+  /**
+   * LangChain 側のモデル種別識別子。LangSmith 等のトレースで使う。
+   * LangChain `_llmType` identifier.
+   */
+  _llmType(): string {
+    return "zedi-chat";
+  }
+
+  /**
+   * 非ストリーミング呼び出し。`callProvider` → cost 計算 → `recordUsage`。
+   * Non-streaming generation path.
+   */
+  async _generate(
+    messages: BaseMessage[],
+    _options: this["ParsedCallOptions"],
+    runManager?: CallbackManagerForLLMRun,
+  ): Promise {
+    const zediMessages = toZediMessages(messages);
+    const result = await this.callProviderFn(
+      this.provider,
+      this.apiKey,
+      this.apiModelId,
+      zediMessages,
+      {
+        temperature: this.temperature,
+        maxTokens: this.maxTokens,
+        feature: this.feature,
+      },
+    );
+
+    const usage = await recordZediUsage({
+      db: this.db,
+      userId: this.userId,
+      modelId: this.modelRowId,
+      feature: this.feature,
+      usage: result.usage,
+      inputCostUnits: this.inputCostUnits,
+      outputCostUnits: this.outputCostUnits,
+      apiMode: this.apiMode,
+    });
+
+    void this.tier;
+    void runManager;
+
+    const aiMessage = new AIMessage({
+      content: result.content,
+      response_metadata: {
+        finishReason: result.finishReason,
+        usage: {
+          inputTokens: usage.inputTokens,
+          outputTokens: usage.outputTokens,
+          costUnits: usage.costUnits,
+        },
+      },
+    });
+
+    return {
+      generations: [
+        {
+          text: result.content,
+          message: aiMessage,
+          generationInfo: { finishReason: result.finishReason },
+        },
+      ],
+      llmOutput: {
+        tokenUsage: {
+          promptTokens: usage.inputTokens,
+          completionTokens: usage.outputTokens,
+          totalTokens: usage.inputTokens + usage.outputTokens,
+        },
+        costUnits: usage.costUnits,
+        finishReason: result.finishReason,
+      },
+    };
+  }
+
+  /**
+   * ストリーミング呼び出し。`streamProvider` の async generator を `ChatGenerationChunk`
+   * に変換しつつ、累積トークンを cost 算出のために保持する。`/api/ai/chat` の挙動
+   * と同じく `chars/4` を fallback 推定とする（プロバイダ側がトークン数を返さない
+   * パスでも課金破綻させない）。
+   *
+   * Streaming generation; mirrors `routes/ai/chat.ts` token-accounting fallback
+   * by estimating with `chars/4` when the provider does not surface usage in a
+   * streaming response.
+   */
+  async *_streamResponseChunks(
+    messages: BaseMessage[],
+    _options: this["ParsedCallOptions"],
+    runManager?: CallbackManagerForLLMRun,
+  ): AsyncGenerator {
+    const zediMessages = toZediMessages(messages);
+    const gen = this.streamProviderFn(this.provider, this.apiKey, this.apiModelId, zediMessages, {
+      temperature: this.temperature,
+      maxTokens: this.maxTokens,
+      feature: this.feature,
+    });
+
+    let accumulated = "";
+    let finishReason: string | undefined;
+    let done = false;
+
+    for await (const chunk of gen) {
+      if (chunk.content) {
+        accumulated += chunk.content;
+        const chatChunk = new ChatGenerationChunk({
+          text: chunk.content,
+          message: new AIMessageChunk({ content: chunk.content }),
+        });
+        // Surface incremental tokens to LangChain callback consumers so any
+        // `streamEvents` listener (e.g. SSE mapper) sees deltas before the
+        // final usage event.
+        await runManager?.handleLLMNewToken(
+          chunk.content,
+          undefined,
+          undefined,
+          undefined,
+          undefined,
+          {
+            chunk: chatChunk,
+          },
+        );
+        yield chatChunk;
+      }
+      if (chunk.done) {
+        finishReason = chunk.finishReason;
+        done = true;
+        break;
+      }
+    }
+
+    // Streaming providers in this codebase do not return token counts; mirror
+    // chat.ts and estimate. Pre-encoded message length is what the user "paid"
+    // for, response length is what they received.
+    const promptLength = zediMessages.reduce((sum, m) => sum + m.content.length, 0);
+    const inputTokens = Math.ceil(promptLength / 4);
+    const outputTokens = Math.ceil(accumulated.length / 4);
+
+    const usage = await recordZediUsage({
+      db: this.db,
+      userId: this.userId,
+      modelId: this.modelRowId,
+      feature: this.feature,
+      usage: { inputTokens, outputTokens },
+      inputCostUnits: this.inputCostUnits,
+      outputCostUnits: this.outputCostUnits,
+      apiMode: this.apiMode,
+    });
+
+    // Final chunk surfaces aggregate usage so downstream consumers (sseMapper,
+    // LangChain callbacks) can read totals from a single ChatGenerationChunk.
+    yield new ChatGenerationChunk({
+      text: "",
+      message: new AIMessageChunk({
+        content: "",
+        response_metadata: {
+          finishReason: finishReason ?? (done ? "stop" : "incomplete"),
+        },
+        usage_metadata: {
+          input_tokens: usage.inputTokens,
+          output_tokens: usage.outputTokens,
+          total_tokens: usage.inputTokens + usage.outputTokens,
+        },
+      }),
+      generationInfo: {
+        finishReason: finishReason ?? (done ? "stop" : "incomplete"),
+        costUnits: usage.costUnits,
+      },
+    });
+  }
+}
diff --git a/server/api/src/agents/core/state/baseState.ts b/server/api/src/agents/core/state/baseState.ts
new file mode 100644
index 00000000..c6cd1b31
--- /dev/null
+++ b/server/api/src/agents/core/state/baseState.ts
@@ -0,0 +1,73 @@
+/**
+ * Base LangGraph state shared by all Wiki Compose subgraphs.
+ *
+ * 全 Wiki Compose subgraph で共通利用する LangGraph state。各 subgraph (#949,
+ * #950, ...) はこの annotation を `Annotation.Root({...BaseState.spec, ...})`
+ * で拡張する想定。messages reducer は `messagesStateReducer` を使い、tool 結果や
+ * ai 応答の追記をフラットに扱う。
+ *
+ * The Wiki Compose family of subgraphs (P1 research, P2 outline, P3 draft …)
+ * all need a messages history plus a few cross-cutting fields. `BaseState`
+ * defines that shared shell; downstream graphs spread its `spec` into their
+ * own `Annotation.Root({...})` to extend it.
+ */
+import { Annotation, messagesStateReducer } from "@langchain/langgraph";
+import type { BaseMessage } from "@langchain/core/messages";
+
+/**
+ * 共通 state スキーマ。
+ * Shared state schema.
+ *
+ * - `messages` — LangGraph 規約に従い、reducer で append する。
+ * - `phase`    — 現在のフェーズ名（subgraph 横断の進行管理）。
+ * - `pageId`   — 対象ページ。サブグラフが書き戻し対象を見失わないために state にも持つ。
+ * - `userId`   — 実行ユーザー。tool が page アクセス権チェックを行う際に参照する。
+ */
+export const BaseState = Annotation.Root({
+  /**
+   * 会話履歴 + tool 結果。`messagesStateReducer` で append マージする。
+   * Conversation + tool messages, accumulated via `messagesStateReducer`.
+   */
+  messages: Annotation({
+    reducer: messagesStateReducer,
+    default: () => [],
+  }),
+  /**
+   * 現在のフェーズ識別子。subgraph 間遷移で書き換えられる。
+   * Current phase identifier; rewritten when transitioning between subgraphs.
+   */
+  phase: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => "init",
+  }),
+  /**
+   * 対象ページ ID。
+   * Target page id.
+   */
+  pageId: Annotation({
+    reducer: (prev, next) => next ?? prev,
+    default: () => "",
+  }),
+  /**
+   * 実行ユーザー ID。
+   * Executing user id.
+   */
+  userId: Annotation({
+    reducer: (prev, next) => next ?? prev,
+    default: () => "",
+  }),
+});
+
+/**
+ * `BaseState` の `State` 型エイリアス。subgraph 側でも `typeof BaseState.State` で
+ * 取得できるが、よく使うため再 export する。
+ *
+ * Convenience type alias for `typeof BaseState.State`.
+ */
+export type BaseStateType = typeof BaseState.State;
+
+/**
+ * `BaseState` の `Update` 型エイリアス。ノードの返却型として使う。
+ * Convenience type alias for `typeof BaseState.Update`.
+ */
+export type BaseStateUpdate = typeof BaseState.Update;
diff --git a/server/api/src/agents/core/tools/fetchArticle.ts b/server/api/src/agents/core/tools/fetchArticle.ts
new file mode 100644
index 00000000..a828d6cc
--- /dev/null
+++ b/server/api/src/agents/core/tools/fetchArticle.ts
@@ -0,0 +1,57 @@
+/**
+ * `fetch_article` tool stub.
+ *
+ * URL を渡すと Readability ベースで本文を抽出する tool（既存 `extractArticleFromUrl`
+ * を将来流用する想定）。P0 ではスキーマだけ確定。
+ *
+ * Article extractor by URL. Real implementation reuses `extractArticleFromUrl`
+ * in `lib/articleExtractor.ts`; P0 only fixes the contract.
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+/** Tool name. */
+export const FETCH_ARTICLE_TOOL_NAME = "fetch_article" as const;
+
+const STUB_RESPONSE_PREFIX = "FETCH_ARTICLE_NOT_IMPLEMENTED";
+
+/**
+ * Input schema. URL は http/https のみ。previewLength は 500〜8000。
+ * Input schema; URL must be http/https, `previewLength` clamps to 500..8000.
+ */
+export const fetchArticleInputSchema = z.object({
+  url: z
+    .string()
+    .url()
+    .refine((u) => /^https?:\/\//i.test(u), "URL must use http or https")
+    .describe("Article URL. 記事 URL。"),
+  previewLength: z
+    .number()
+    .int()
+    .min(500)
+    .max(8000)
+    .optional()
+    .describe("Extracted excerpt length (default 4000). 抜粋長 (既定 4000)。"),
+});
+
+/**
+ * P0 stub. Real implementation routes through `extractArticleFromUrl` with the
+ * same SSRF guards (`isAllowedUrlForArticleFetch`) already used by `/api/clip`
+ * and `/api/ingest/plan`.
+ *
+ * P0 スタブ。実装は `extractArticleFromUrl` を経由し、`/api/clip` 等と同じ
+ * SSRF 防御 (`isAllowedUrlForArticleFetch`) を通す。
+ */
+export const fetchArticleTool = tool(
+  async (input) => {
+    const summary = `${STUB_RESPONSE_PREFIX} url=${JSON.stringify(input.url)}`;
+    return summary;
+  },
+  {
+    name: FETCH_ARTICLE_TOOL_NAME,
+    description:
+      "Fetch and extract the main article body from a URL. Returns title, content, and source metadata. " +
+      "URL から本文を抽出し、タイトル・本文・メタ情報を返す。",
+    schema: fetchArticleInputSchema,
+  },
+);
diff --git a/server/api/src/agents/core/tools/imageSearch.ts b/server/api/src/agents/core/tools/imageSearch.ts
new file mode 100644
index 00000000..e43b748d
--- /dev/null
+++ b/server/api/src/agents/core/tools/imageSearch.ts
@@ -0,0 +1,46 @@
+/**
+ * `image_search` tool stub.
+ *
+ * Wiki Compose の thumbnail 提案フェーズ向け画像検索 tool。実装は `services/imageSearch.ts`
+ * の Google Custom Search 経由に置き換え予定。P0 はスキーマと名前だけ確定する。
+ *
+ * Image search tool stub. Real implementation will reuse `services/imageSearch.ts`
+ * (Google Custom Search). P0 only nails down name + schema.
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+/** Tool name. */
+export const IMAGE_SEARCH_TOOL_NAME = "image_search" as const;
+
+const STUB_RESPONSE_PREFIX = "IMAGE_SEARCH_NOT_IMPLEMENTED";
+
+/**
+ * Input schema. `query` 必須、`limit` 1〜10、`page` 1〜10。
+ * Input schema.
+ */
+export const imageSearchInputSchema = z.object({
+  query: z.string().min(1).describe("Image search query. 画像検索クエリ。"),
+  limit: z.number().int().min(1).max(10).optional().describe("Max results. 最大件数。"),
+  page: z.number().int().min(1).max(10).optional().describe("Page number. ページ番号。"),
+});
+
+/**
+ * P0 stub. Real implementation reads `GOOGLE_CSE_API_KEY` /
+ * `GOOGLE_CSE_ENGINE_ID` (matching `services/imageSearch.ts`).
+ *
+ * P0 スタブ。実装は既存の Google CSE 環境変数を流用する。
+ */
+export const imageSearchTool = tool(
+  async (input) => {
+    const summary = `${STUB_RESPONSE_PREFIX} query=${JSON.stringify(input.query)}`;
+    return summary;
+  },
+  {
+    name: IMAGE_SEARCH_TOOL_NAME,
+    description:
+      "Search images for a query and return preview URLs + source attribution. " +
+      "画像を検索しプレビュー URL と帰属情報を返す。",
+    schema: imageSearchInputSchema,
+  },
+);
diff --git a/server/api/src/agents/core/tools/index.ts b/server/api/src/agents/core/tools/index.ts
new file mode 100644
index 00000000..687a0c22
--- /dev/null
+++ b/server/api/src/agents/core/tools/index.ts
@@ -0,0 +1,36 @@
+/**
+ * Tool registry for Wiki Compose subgraphs.
+ *
+ * 全 subgraph で共有する LangGraph tool 一式。subgraph は本ファイルから tool を
+ * import し、`model.bindTools([...])` で束ねて利用する。各 tool の本体は P0 では
+ * スタブだが、bind 経路と zod schema は実装と同じ形に固定してある。
+ *
+ * Aggregate barrel exposing the shared tool set. Subgraphs import individual
+ * tools from here and bind them with `bindTools`. P0 ships stubs; the schemas
+ * are frozen so swapping in real implementations is non-breaking.
+ */
+export { WEB_SEARCH_TOOL_NAME, webSearchInputSchema, webSearchTool } from "./webSearch.js";
+export { WIKI_SEARCH_TOOL_NAME, wikiSearchInputSchema, wikiSearchTool } from "./wikiSearch.js";
+export {
+  FETCH_ARTICLE_TOOL_NAME,
+  fetchArticleInputSchema,
+  fetchArticleTool,
+} from "./fetchArticle.js";
+export { IMAGE_SEARCH_TOOL_NAME, imageSearchInputSchema, imageSearchTool } from "./imageSearch.js";
+
+import { webSearchTool } from "./webSearch.js";
+import { wikiSearchTool } from "./wikiSearch.js";
+import { fetchArticleTool } from "./fetchArticle.js";
+import { imageSearchTool } from "./imageSearch.js";
+
+/**
+ * P0 で共有 tool として bind 可能な配列。subgraph がそのまま `bindTools` に渡せる。
+ *
+ * Convenience array of all shared tools, ready for `bindTools([...])`.
+ */
+export const SHARED_TOOLS = [
+  webSearchTool,
+  wikiSearchTool,
+  fetchArticleTool,
+  imageSearchTool,
+] as const;
diff --git a/server/api/src/agents/core/tools/webSearch.ts b/server/api/src/agents/core/tools/webSearch.ts
new file mode 100644
index 00000000..dbfa4bdd
--- /dev/null
+++ b/server/api/src/agents/core/tools/webSearch.ts
@@ -0,0 +1,61 @@
+/**
+ * `web_search` tool stub for the Wiki Compose research subgraph (#949).
+ *
+ * Web 検索 tool のスタブ。本実装は #949 (P1 調査 subgraph) で行うが、P0 では
+ * LangGraph tool として bind 可能な形と zod スキーマ・名前空間だけ確定させ、
+ * 呼び出し時は `WEB_SEARCH_NOT_IMPLEMENTED` を返す。
+ *
+ * Stub web search tool. P0 only fixes the name + zod schema so subgraphs can
+ * `bindTools([webSearchTool])` without breakage; behaviour ships in #949.
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+/** Tool name shared across subgraphs. 全 subgraph 共通の tool 名。 */
+export const WEB_SEARCH_TOOL_NAME = "web_search" as const;
+
+/** Stub response surfaced when the tool is called before #949 lands. */
+const STUB_RESPONSE_PREFIX = "WEB_SEARCH_NOT_IMPLEMENTED";
+
+/**
+ * Input schema (zod). `query` は必須、`limit` は 1〜10、`recencyDays` は省略可。
+ * Input schema; `query` required, `limit` 1..10, `recencyDays` optional.
+ */
+export const webSearchInputSchema = z.object({
+  query: z.string().min(1).describe("Search query string. 検索クエリ。"),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(10)
+    .optional()
+    .describe("Max results (default 5). 最大件数 (既定 5)。"),
+  recencyDays: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe("Restrict to results within N days. N 日以内の結果に限定。"),
+});
+
+/**
+ * P0 stub. Bound by subgraphs via `model.bindTools([webSearchTool])`. The body
+ * intentionally returns a sentinel string so research subgraphs that depend on
+ * it surface a visible failure mode rather than silent empty results.
+ *
+ * P0 スタブ。呼び出されたら sentinel を返し、依存する subgraph が静かに空結果を
+ * 受け取るのを防ぐ。
+ */
+export const webSearchTool = tool(
+  async (input) => {
+    const summary = `${STUB_RESPONSE_PREFIX} query=${JSON.stringify(input.query)}`;
+    return summary;
+  },
+  {
+    name: WEB_SEARCH_TOOL_NAME,
+    description:
+      "Search the public web for fresh information. Returns top results with title + snippet + url. " +
+      "公開 Web を検索し、タイトル・抜粋・URL を返す。",
+    schema: webSearchInputSchema,
+  },
+);
diff --git a/server/api/src/agents/core/tools/wikiSearch.ts b/server/api/src/agents/core/tools/wikiSearch.ts
new file mode 100644
index 00000000..decb146d
--- /dev/null
+++ b/server/api/src/agents/core/tools/wikiSearch.ts
@@ -0,0 +1,53 @@
+/**
+ * `wiki_search` tool stub.
+ *
+ * ユーザー所有 Wiki 内のページ検索 tool。P0 ではスキーマと名前のみ固定し、
+ * 中身は #949 (P1 調査 subgraph) で `/api/search` 相当のクエリに置き換える。
+ *
+ * Searches the executing user's wiki. P0 ships only the schema and name so
+ * subgraphs can wire it up; the real implementation lands in #949.
+ */
+import { tool } from "@langchain/core/tools";
+import { z } from "zod";
+
+/** Tool name. */
+export const WIKI_SEARCH_TOOL_NAME = "wiki_search" as const;
+
+const STUB_RESPONSE_PREFIX = "WIKI_SEARCH_NOT_IMPLEMENTED";
+
+/**
+ * Input schema. `query` は必須、`limit` は 1〜20。
+ * Input schema.
+ */
+export const wikiSearchInputSchema = z.object({
+  query: z.string().min(1).describe("Title / body keyword. タイトル・本文キーワード。"),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .optional()
+    .describe("Max results (default 10). 最大件数 (既定 10)。"),
+});
+
+/**
+ * P0 stub. Authorisation will be enforced by the future implementation: it must
+ * filter by the executing user's owner_id pulled from `GraphContext.userId`,
+ * not by any tool argument.
+ *
+ * P0 スタブ。実実装は `GraphContext.userId` から owner_id を取り出して絞り込み
+ * する。tool 引数から userId を取らないこと（権限境界）。
+ */
+export const wikiSearchTool = tool(
+  async (input) => {
+    const summary = `${STUB_RESPONSE_PREFIX} query=${JSON.stringify(input.query)}`;
+    return summary;
+  },
+  {
+    name: WIKI_SEARCH_TOOL_NAME,
+    description:
+      "Search the executing user's own wiki pages by keyword. Returns matching page ids + titles + excerpts. " +
+      "実行ユーザーの Wiki ページを検索し、ID・タイトル・抜粋を返す。",
+    schema: wikiSearchInputSchema,
+  },
+);
diff --git a/server/api/src/agents/core/types/executionBackend.ts b/server/api/src/agents/core/types/executionBackend.ts
new file mode 100644
index 00000000..c565c3ee
--- /dev/null
+++ b/server/api/src/agents/core/types/executionBackend.ts
@@ -0,0 +1,33 @@
+/**
+ * Execution backend identifies where the LangGraph agent runs and which
+ * credential mode applies.
+ *
+ * 実行バックエンド。LangGraph エージェントが「どこで・誰の鍵で」走るかを表す。
+ *
+ * - `zedi_managed` — Zedi がプロビジョニングしたシステム API キーで API
+ *   ホスト内で実行する。月次予算・利用記録は `recordUsage` を通る。これが
+ *   P0 (#948) で唯一サポートされる backend。
+ * - `byok` — ユーザーが自分の API キーを持ち込んで API ホスト内で実行する。
+ *   P0 では未対応 (#951 で導入)。
+ * - `byo_runner` — ユーザー所有のランナー（将来の self-host 想定）。P0 では
+ *   未対応で予約済み。
+ *
+ * `zedi_managed` is the only backend supported in P0 (#948). `byok` and
+ * `byo_runner` are reserved for follow-ups (#951 and later) so the column
+ * shape can stabilise before behaviour is wired up.
+ */
+export type ExecutionBackend = "zedi_managed" | "byok" | "byo_runner";
+
+/**
+ * P0 で受け入れる backend のホワイトリスト。
+ * Whitelist of backends accepted in P0.
+ */
+export const SUPPORTED_BACKENDS_P0: ReadonlyArray = ["zedi_managed"];
+
+/**
+ * 与えられた値が `ExecutionBackend` の文字列かどうかを判定する。
+ * Type guard for `ExecutionBackend`.
+ */
+export function isExecutionBackend(value: unknown): value is ExecutionBackend {
+  return value === "zedi_managed" || value === "byok" || value === "byo_runner";
+}
diff --git a/server/api/src/agents/core/types/graphContext.ts b/server/api/src/agents/core/types/graphContext.ts
new file mode 100644
index 00000000..30774ffe
--- /dev/null
+++ b/server/api/src/agents/core/types/graphContext.ts
@@ -0,0 +1,48 @@
+/**
+ * Graph execution context passed via `LangGraphRunnableConfig.configurable`.
+ *
+ * グラフ実行コンテキスト。`GraphRunner` がノードや tool に渡す共有情報をまとめる。
+ * LangGraph の `configurable` には `thread_id` と `pageId`・`userId` 等の識別子を
+ * 載せ、`callbacks` には `ZediChatModel` の usage 記録コールバックを載せる。
+ *
+ * Shared per-run context that the `GraphRunner` propagates into LangGraph
+ * `configurable`. Includes the LangGraph `thread_id` plus Zedi-specific
+ * identifiers required by `ZediChatModel` for usage attribution.
+ */
+import type { Database, UserTier } from "../../../types/index.js";
+import type { ExecutionBackend } from "./executionBackend.js";
+
+/**
+ * グラフ実行 1 回ぶんのコンテキスト。
+ * Per-execution graph context.
+ *
+ * @property threadId  LangGraph 内 thread_id（compose session id を流用）。
+ *                     LangGraph thread id; reuse compose-session id.
+ * @property userId    実行ユーザー ID。Executing user id.
+ * @property pageId    対象ページ ID。Target page id.
+ * @property sessionId compose_session 行 ID（threadId と同じ値が来る想定）。
+ *                     compose session row id (currently equals threadId).
+ * @property graphId   実行する graph の論理名 (registry key)。Logical graph id.
+ * @property backend   実行 backend (P0 は `zedi_managed` のみ)。Execution backend.
+ * @property tier      ユーザー tier（usage 上限判定で使う）。User tier for budget checks.
+ * @property db        Drizzle DB ハンドル。Drizzle DB handle.
+ * @property feature   `recordUsage` の feature ラベル。`recordUsage` feature label.
+ */
+export interface GraphContext {
+  threadId: string;
+  userId: string;
+  pageId: string;
+  sessionId: string;
+  graphId: string;
+  backend: ExecutionBackend;
+  tier: UserTier;
+  db: Database;
+  feature: string;
+}
+
+/**
+ * LangGraph の `configurable` バッグへ載せるキー。tool / node から `config.configurable`
+ * 経由でアクセスする際は必ず本キー名を使う。
+ * Single key namespace on `configurable` to fetch a {@link GraphContext}.
+ */
+export const GRAPH_CONTEXT_CONFIG_KEY = "zediGraphContext" as const;
diff --git a/server/api/src/agents/core/types/index.ts b/server/api/src/agents/core/types/index.ts
new file mode 100644
index 00000000..6d41765f
--- /dev/null
+++ b/server/api/src/agents/core/types/index.ts
@@ -0,0 +1,27 @@
+/**
+ * Barrel for `agents/core/types/*`. Keeps import sites stable as new types are
+ * added; callers should import from this file rather than the individual
+ * modules.
+ *
+ * `agents/core/types/*` のバレル。呼び出し側は個別ファイルではなく本ファイル
+ * から import することで、サブモジュール構成の変更に追従しやすくする。
+ */
+export {
+  type ExecutionBackend,
+  isExecutionBackend,
+  SUPPORTED_BACKENDS_P0,
+} from "./executionBackend.js";
+export { type GraphContext, GRAPH_CONTEXT_CONFIG_KEY } from "./graphContext.js";
+export {
+  type SseEvent,
+  type SseStartedEvent,
+  type SseStatusEvent,
+  type SseTokenEvent,
+  type SseToolStartEvent,
+  type SseToolEndEvent,
+  type SseUsageEvent,
+  type SseInterruptEvent,
+  type SseDoneEvent,
+  type SseErrorEvent,
+  SSE_EVENT_NAMES,
+} from "./sseEvents.js";
diff --git a/server/api/src/agents/core/types/sseEvents.ts b/server/api/src/agents/core/types/sseEvents.ts
new file mode 100644
index 00000000..4ed33715
--- /dev/null
+++ b/server/api/src/agents/core/types/sseEvents.ts
@@ -0,0 +1,141 @@
+/**
+ * Wire-level SSE event types emitted from `POST /api/pages/:pageId/compose-sessions/:id/run`.
+ *
+ * compose-session 実行ストリームが SSE で吐く wire イベント型。フロントエンドは
+ * `event: ` でフィルタリングし、`data` を本ファイルの discriminated union
+ * として扱う。`sseMapper.ts` が LangGraph の生イベントから本型へ変換する。
+ *
+ * Discriminated union of SSE payloads sent by the compose-session run endpoint.
+ * The frontend treats `data` as a JSON document and discriminates on `type`.
+ * `sseMapper.ts` converts LangGraph runtime events into this shape.
+ */
+
+/**
+ * セッション開始通知。クライアントがプログレス UI を初期化するための合図。
+ * Emitted once when the run starts; lets the client initialise progress UI.
+ */
+export interface SseStartedEvent {
+  type: "started";
+  sessionId: string;
+  graphId: string;
+  phase?: string;
+}
+
+/**
+ * フェーズ遷移通知。subgraph が次フェーズに進んだとき。
+ * Phase transition (e.g. "research" → "draft").
+ */
+export interface SseStatusEvent {
+  type: "status";
+  phase: string;
+  message?: string;
+}
+
+/**
+ * LLM テキストトークン。compose の本文ドラフトをインクリメンタル描画する用途。
+ * Token delta from the underlying chat model for incremental rendering.
+ */
+export interface SseTokenEvent {
+  type: "token";
+  /** ノード名（draft / outline 等）。Node label, e.g. "draft". */
+  node?: string;
+  content: string;
+}
+
+/**
+ * Tool 呼び出し開始。UI 上の「検索中…」「記事取得中…」表示用。
+ * Tool invocation started.
+ */
+export interface SseToolStartEvent {
+  type: "tool_start";
+  tool: string;
+  /** zod でバリデート済みの入力。Validated tool input. */
+  input?: Record;
+}
+
+/**
+ * Tool 呼び出し終了。
+ * Tool invocation finished.
+ */
+export interface SseToolEndEvent {
+  type: "tool_end";
+  tool: string;
+  /** クライアントには内容を晒さず長さだけ載せる用途で `outputLength` を許容。 */
+  outputLength?: number;
+  error?: string;
+}
+
+/**
+ * Usage 更新通知。トークン課金後に走る。
+ * Usage snapshot emitted after `recordUsage`.
+ */
+export interface SseUsageEvent {
+  type: "usage";
+  inputTokens: number;
+  outputTokens: number;
+  costUnits: number;
+  usagePercent: number;
+}
+
+/**
+ * Human-in-the-loop interrupt。次の resume で再開可能なポイント。
+ * Human-in-the-loop interrupt point; resumable via PATCH resume.
+ */
+export interface SseInterruptEvent {
+  type: "interrupt";
+  /** クライアントに渡す任意の追加情報。Optional payload describing the interrupt. */
+  payload?: unknown;
+}
+
+/**
+ * 終了イベント。`status` でステータスを伝達。
+ * Terminal event; carries the final status.
+ */
+export interface SseDoneEvent {
+  type: "done";
+  status: "completed" | "interrupted" | "failed";
+}
+
+/**
+ * エラーイベント。`SseDoneEvent` とは別に詳細を伝える。
+ * Error event with provider-side message; pair with a `done` with status="failed".
+ */
+export interface SseErrorEvent {
+  type: "error";
+  message: string;
+  /** リトライ可能か（ネットワーク等）。Whether the client can retry. */
+  retryable?: boolean;
+}
+
+/**
+ * Wire-level SSE union.
+ */
+export type SseEvent =
+  | SseStartedEvent
+  | SseStatusEvent
+  | SseTokenEvent
+  | SseToolStartEvent
+  | SseToolEndEvent
+  | SseUsageEvent
+  | SseInterruptEvent
+  | SseDoneEvent
+  | SseErrorEvent;
+
+/**
+ * SSE event 名（`event:` 行に流す名前）。`SseEvent["type"]` と同値だが、
+ * 文字列リテラルとして引きやすいよう列挙する。
+ *
+ * SSE event names mirroring `SseEvent["type"]`, exposed as a const so writers
+ * can `event: SSE_EVENT_NAMES.token` without re-spelling literals.
+ */
+export const SSE_EVENT_NAMES = {
+  started: "started",
+  status: "status",
+  token: "token",
+  toolStart: "tool_start",
+  toolEnd: "tool_end",
+  usage: "usage",
+  interrupt: "interrupt",
+  done: "done",
+  error: "error",
+} as const satisfies Record;
diff --git a/server/api/src/agents/index.ts b/server/api/src/agents/index.ts
new file mode 100644
index 00000000..93313f29
--- /dev/null
+++ b/server/api/src/agents/index.ts
@@ -0,0 +1,70 @@
+/**
+ * Wiki Compose agent infrastructure — public barrel.
+ *
+ * `server/api` の他レイヤから agent モジュールを参照する際の唯一の入口。サブ
+ * パス (`agents/runner/...` 等) を直接 import するより、本ファイル経由で抽象を
+ * 維持することで、内部リファクタの影響範囲を限定する。
+ *
+ * Single entry barrel for the agent subsystem. External callers (routes,
+ * services, scripts) import from here so internal directory shuffles do not
+ * cascade across the codebase.
+ *
+ * Issue: otomatty/zedi#948
+ */
+export {
+  ZediChatModel,
+  type ZediChatModelParams,
+  type CallProviderFn,
+  type StreamProviderFn,
+} from "./core/llm/zediChatModel.js";
+export {
+  createZediChatModel,
+  assertSupportedBackendP0,
+  UnsupportedBackendError,
+  type CreateZediChatModelInput,
+} from "./core/llm/modelFactory.js";
+export {
+  recordZediUsage,
+  toZediMessages,
+  type RecordZediUsageInput,
+  type RecordZediUsageResult,
+} from "./core/llm/usageCallback.js";
+export {
+  getPostgresCheckpointer,
+  ensurePostgresCheckpointerSetup,
+  resolveCheckpointerForRun,
+} from "./core/checkpoint/index.js";
+export { BaseState, type BaseStateType, type BaseStateUpdate } from "./core/state/baseState.js";
+export {
+  SHARED_TOOLS,
+  webSearchTool,
+  wikiSearchTool,
+  fetchArticleTool,
+  imageSearchTool,
+} from "./core/tools/index.js";
+export * from "./core/types/index.js";
+export {
+  registerGraph,
+  getRegisteredGraph,
+  listRegisteredGraphs,
+  GraphNotRegisteredError,
+  type GraphFactory,
+  type GraphFactoryInput,
+  type RegisteredGraph,
+} from "./registry/graphRegistry.js";
+export { STUB_GRAPH_ID, registerStubGraph } from "./registry/stubGraph.js";
+export {
+  GraphRunner,
+  type RunInput,
+  type RunPayload,
+  type RunResult,
+} from "./runner/graphRunner.js";
+export {
+  mapLangGraphEvent,
+  startedEvent,
+  statusEvent,
+  usageEvent,
+  doneEvent,
+  errorEvent,
+  type LangGraphRuntimeEvent,
+} from "./runner/sseMapper.js";
diff --git a/server/api/src/agents/registry/graphRegistry.ts b/server/api/src/agents/registry/graphRegistry.ts
new file mode 100644
index 00000000..eb76b4ff
--- /dev/null
+++ b/server/api/src/agents/registry/graphRegistry.ts
@@ -0,0 +1,118 @@
+/**
+ * Graph registry — maps a logical `graphId` to a factory that produces a
+ * compiled LangGraph.
+ *
+ * Wiki Compose は複数のグラフ (P1 調査, P2 outline, P3 draft, ...) を
+ * `graphId` で切り替える。本ファイルは「論理 ID → コンパイル済みグラフを
+ * 返すファクトリ」のマップを 1 つに集約し、route 層・GraphRunner からは
+ * registry を介してのみグラフを引く。
+ *
+ * Each compose session is parameterised by a `graphId` so the platform can
+ * evolve P1..P4 subgraphs independently. The registry is the only place where
+ * `graphId → graph` mapping lives — routes and the runner depend on it, never
+ * on concrete graph modules.
+ */
+import type { BaseCheckpointSaver } from "@langchain/langgraph";
+
+/**
+ * LangGraph `compile()` の戻り値はジェネリック型パラメータが多すぎて registry
+ * 側で完全に再現できない。registry は run / streamEvents / invoke の呼び出し
+ * できる最小契約だけ要求する構造的な型を使う。
+ *
+ * `CompiledGraph` from LangGraph is heavily generic; pinning all type
+ * parameters in the registry would force every subgraph to re-export them.
+ * The registry only relies on the runtime methods used by `GraphRunner`, so
+ * a structural type covers our needs without leaking generic parameters.
+ */
+export interface CompiledGraphLike {
+  invoke(input: unknown, options?: unknown): Promise;
+  stream(input: unknown, options?: unknown): Promise;
+  streamEvents(input: unknown, options: unknown): unknown;
+}
+
+/**
+ * グラフファクトリ。1 セッションごとに呼ばれ、必要なら checkpointer を bake する。
+ * Graph factory: called once per session; may consume the runtime checkpointer.
+ *
+ * @param ctx.checkpointer  実行時に GraphRunner が注入する LangGraph saver。
+ *                          The checkpointer injected by the runner at execution time.
+ * @returns CompiledGraph   `compile()` 済みのグラフインスタンス。
+ *                          Compiled graph instance returned by `StateGraph.compile()`.
+ */
+export interface GraphFactoryInput {
+  checkpointer: BaseCheckpointSaver | boolean;
+}
+export interface GraphFactory {
+  (input: GraphFactoryInput): CompiledGraphLike;
+}
+
+/**
+ * グラフ定義のメタ情報。registry が外部に公開する unit。
+ * Registered graph descriptor.
+ *
+ * @property id           論理 ID。Route layer / DB の `graphId` カラム。
+ * @property version      バージョン文字列。デプロイ間で挙動が変わった時に bump。
+ * @property phase        グラフが属するフェーズ識別子（"research", "draft" 等）。
+ * @property description  Human-readable 説明。Admin UI 等で利用。
+ * @property factory      コンパイル済みグラフを返すファクトリ。
+ */
+export interface RegisteredGraph {
+  id: string;
+  version: string;
+  phase: string;
+  description: string;
+  factory: GraphFactory;
+}
+
+const registry = new Map();
+
+/**
+ * Register a graph. Calling twice with the same id replaces the previous entry
+ * (intended for hot-reload during dev / test).
+ *
+ * グラフを登録する。同じ id を 2 度登録すると上書きされる（dev / test 向け）。
+ */
+export function registerGraph(graph: RegisteredGraph): void {
+  registry.set(graph.id, graph);
+}
+
+/**
+ * Look up a registered graph by id.
+ * 登録済みグラフを id で取得する。未登録なら undefined。
+ */
+export function getRegisteredGraph(id: string): RegisteredGraph | undefined {
+  return registry.get(id);
+}
+
+/**
+ * 全登録グラフを列挙する。管理画面・デバッグ用。
+ * Enumerate all registered graphs.
+ */
+export function listRegisteredGraphs(): RegisteredGraph[] {
+  return Array.from(registry.values());
+}
+
+/**
+ * テスト用：レジストリをクリアする。
+ * Test-only: clear the registry.
+ */
+export function __resetRegistryForTests(): void {
+  registry.clear();
+}
+
+/**
+ * `graphId` 未登録時の例外。route 層で 400 に変換する。
+ *
+ * Thrown by the runner when a session references an unknown `graphId`. The
+ * route layer should translate this into a 400, since the value comes from
+ * client input.
+ */
+export class GraphNotRegisteredError extends Error {
+  readonly code = "GRAPH_NOT_REGISTERED";
+  readonly graphId: string;
+  constructor(graphId: string) {
+    super(`No graph registered with id="${graphId}"`);
+    this.name = "GraphNotRegisteredError";
+    this.graphId = graphId;
+  }
+}
diff --git a/server/api/src/agents/registry/stubGraph.ts b/server/api/src/agents/registry/stubGraph.ts
new file mode 100644
index 00000000..33710a45
--- /dev/null
+++ b/server/api/src/agents/registry/stubGraph.ts
@@ -0,0 +1,42 @@
+/**
+ * Stub Wiki Compose graph used by the P0 plumbing.
+ *
+ * `wiki-compose-stub` グラフ。P0 (#948) 段階で `GraphRunner` がレジストリ経由で
+ * グラフを実行できることを確認するための最小グラフ。1 ノードで `phase` を
+ * "completed" にして終了する。本物の調査・outline・draft グラフは #949 以降で
+ * 別 graphId として登録する。
+ *
+ * Minimal compiled graph for P0 wiring tests. Real Wiki Compose subgraphs land
+ * in #949+ under separate ids; this stub stays as a smoke-test fixture.
+ */
+import { END, START, StateGraph } from "@langchain/langgraph";
+import { BaseState } from "../core/state/baseState.js";
+import { registerGraph, type GraphFactory } from "./graphRegistry.js";
+
+/** Registered id for the stub graph. スタブグラフの登録 ID。 */
+export const STUB_GRAPH_ID = "wiki-compose-stub" as const;
+
+const stubFactory: GraphFactory = ({ checkpointer }) => {
+  const builder = new StateGraph(BaseState)
+    .addNode("noop", async (_state) => ({ phase: "completed" }))
+    .addEdge(START, "noop")
+    .addEdge("noop", END);
+  return builder.compile({ checkpointer });
+};
+
+/**
+ * Register the stub graph. Called from app bootstrap so the runner can resolve
+ * it via `graphId="wiki-compose-stub"`.
+ *
+ * スタブグラフを登録する。app 起動時に 1 度呼ぶ。
+ */
+export function registerStubGraph(): void {
+  registerGraph({
+    id: STUB_GRAPH_ID,
+    version: "0.1.0",
+    phase: "stub",
+    description:
+      "P0 wiring smoke test graph. Marks the session 'completed' and exits. Not for production composing.",
+    factory: stubFactory,
+  });
+}
diff --git a/server/api/src/agents/runner/graphRunner.ts b/server/api/src/agents/runner/graphRunner.ts
new file mode 100644
index 00000000..7babb64a
--- /dev/null
+++ b/server/api/src/agents/runner/graphRunner.ts
@@ -0,0 +1,172 @@
+/**
+ * `GraphRunner` — orchestrates LangGraph runs for compose sessions.
+ *
+ * compose-session の実行を司るランナー。route 層が `start` / `streamEvents` /
+ * `resume` を呼ぶ際の入口で、(1) registry からグラフを引く、(2) checkpointer を
+ * 注入する、(3) `GraphContext` を `configurable` に詰める、を一手に引き受ける。
+ *
+ * Single entry point that the route layer uses to start, stream, or resume a
+ * compose session. Owning the checkpointer + registry handoff in one place
+ * keeps individual route handlers thin.
+ */
+import { Command, type BaseCheckpointSaver } from "@langchain/langgraph";
+import { getRegisteredGraph, GraphNotRegisteredError } from "../registry/graphRegistry.js";
+import type { GraphContext } from "../core/types/graphContext.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../core/types/graphContext.js";
+
+/**
+ * `GraphRunner` 共通入力。`context.threadId` を LangGraph `thread_id` に対応させる。
+ * Common input passed to all `GraphRunner` methods.
+ *
+ * @property graphId       Registry に登録済みの論理 ID。Registered logical id.
+ * @property context       Per-execution context propagated into `configurable`.
+ * @property checkpointer  LangGraph checkpoint saver。Postgres or memory.
+ * @property recursionLimit  LangGraph 再帰深度上限（既定 25）。Recursion limit.
+ */
+export interface RunInput {
+  graphId: string;
+  context: GraphContext;
+  checkpointer: BaseCheckpointSaver | boolean;
+  recursionLimit?: number;
+}
+
+/**
+ * `start` / `resume` の payload を共通化するためのユニオン。`Command` を直接
+ * 渡すか、ノードへの input オブジェクトを渡すかを区別する。
+ *
+ * Discriminates between "kick the graph with an input object" and "resume from
+ * an interrupt via `Command`".
+ */
+export type RunPayload = { kind: "input"; value: unknown } | { kind: "command"; value: Command };
+
+/**
+ * 1 セッションの最終結果。successful run なら output、interrupt で停止したら
+ * `interruptedAt` のノード名を持つ。
+ *
+ * Terminal result of a single run.
+ */
+export interface RunResult {
+  status: "completed" | "interrupted" | "failed";
+  output?: unknown;
+  interruptedAt?: string;
+  error?: string;
+}
+
+/**
+ * `GraphRunner` の実体。stateless で、毎呼び出しごとに registry + checkpointer
+ * を解決する。
+ *
+ * Stateless runner; resolves registry + checkpointer per call so the same
+ * instance can serve many concurrent sessions.
+ */
+export class GraphRunner {
+  /**
+   * グラフを 1 回 invoke して結果を返す。ストリーミング不要なテストや、graph
+   * の起動時セルフチェック用の薄い経路。
+   *
+   * One-shot `invoke`. Useful for tests and any non-streaming caller.
+   */
+  async invoke(input: RunInput, payload: RunPayload): Promise {
+    const graph = this.resolveGraph(input.graphId, input.checkpointer);
+    const config = this.buildConfig(input);
+    try {
+      const result = await graph.invoke(this.unwrapPayload(payload), config);
+      return { status: "completed", output: result };
+    } catch (err) {
+      // Interrupts surface as throws in LangGraph; the route layer maps these
+      // back to a 200 with `status: "interrupted"` so we do the same here.
+      // LangGraph の interrupt は例外として伝搬する。`isGraphInterrupt` で判定。
+      if (isInterruptError(err)) {
+        return { status: "interrupted", interruptedAt: extractInterruptNode(err) };
+      }
+      return { status: "failed", error: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
+  /**
+   * `streamEvents(version: "v2")` のラッパー。route 層から SSE に流すための
+   * AsyncIterable を返す。`mapLangGraphEvent` でフィルタリングする想定だが、本層
+   * では生イベントをそのまま流す（マッピング責務は呼び出し側）。
+   *
+   * Streams LangGraph runtime events. The caller (route layer) typically pipes
+   * the result through `mapLangGraphEvent` from `sseMapper.ts`.
+   */
+  streamEvents(input: RunInput, payload: RunPayload): AsyncIterable {
+    const graph = this.resolveGraph(input.graphId, input.checkpointer);
+    const config = this.buildConfig(input);
+    // `streamEvents` returns an `IterableReadableStream<...>`; we return it as
+    // `AsyncIterable` to keep the runner's surface area provider-agnostic.
+    return graph.streamEvents(this.unwrapPayload(payload), {
+      ...config,
+      version: "v2",
+    }) as unknown as AsyncIterable;
+  }
+
+  /**
+   * `Command({ resume: ... })` を流して中断点から再開する。`patchState` は
+   * `resume.value` に対する追加情報（ユーザー入力など）を載せる用途。
+   *
+   * Resume a previously-interrupted run by submitting a `Command({ resume })`
+   * keyed by the session's `thread_id`.
+   */
+  async resume(
+    input: RunInput,
+    resumeValue: unknown,
+    options?: { stream?: false },
+  ): Promise;
+  async resume(
+    input: RunInput,
+    resumeValue: unknown,
+    options: { stream: true },
+  ): Promise>;
+  async resume(
+    input: RunInput,
+    resumeValue: unknown,
+    options?: { stream?: boolean },
+  ): Promise> {
+    const command = new Command({ resume: resumeValue });
+    if (options?.stream) {
+      return this.streamEvents(input, { kind: "command", value: command });
+    }
+    return this.invoke(input, { kind: "command", value: command });
+  }
+
+  private resolveGraph(graphId: string, checkpointer: BaseCheckpointSaver | boolean) {
+    const registered = getRegisteredGraph(graphId);
+    if (!registered) throw new GraphNotRegisteredError(graphId);
+    return registered.factory({ checkpointer });
+  }
+
+  private buildConfig(input: RunInput) {
+    return {
+      configurable: {
+        thread_id: input.context.threadId,
+        [GRAPH_CONTEXT_CONFIG_KEY]: input.context,
+      },
+      recursionLimit: input.recursionLimit ?? 25,
+    };
+  }
+
+  private unwrapPayload(payload: RunPayload): unknown {
+    return payload.kind === "command" ? payload.value : payload.value;
+  }
+}
+
+/**
+ * LangGraph の interrupt 例外判定。`isGraphInterrupt` を直接 import すると
+ * 循環依存のリスクがあるため、本ファイルでは structural にチェックする。
+ *
+ * Structural check for LangGraph `GraphInterrupt`. We avoid importing the
+ * symbol directly to keep this module decoupled from LangGraph internals.
+ */
+function isInterruptError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return typeof name === "string" && /Interrupt/.test(name);
+}
+
+function extractInterruptNode(err: unknown): string | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  const node = (err as { node?: unknown }).node;
+  return typeof node === "string" ? node : undefined;
+}
diff --git a/server/api/src/agents/runner/sseMapper.ts b/server/api/src/agents/runner/sseMapper.ts
new file mode 100644
index 00000000..77b07ed1
--- /dev/null
+++ b/server/api/src/agents/runner/sseMapper.ts
@@ -0,0 +1,162 @@
+/**
+ * `sseMapper` — translate LangGraph runtime events into wire SSE events.
+ *
+ * LangGraph の `streamEvents` 出力を本リポジトリの `SseEvent` discriminated union
+ * に変換する純粋関数群。route 層は `mapLangGraphEvent` の結果を `streamSSE` で
+ * `event:` ＋ `data:` の 2 行として書き出す。テストしやすいよう、I/O を持たない
+ * 同期関数として実装する。
+ *
+ * Pure-function mappers from LangGraph runtime events to {@link SseEvent}. The
+ * route layer is responsible for actually writing to the SSE response; this
+ * file only describes the shape transformation so unit tests can pin it.
+ */
+import type { SseEvent } from "../core/types/sseEvents.js";
+
+/**
+ * 起動時 SSE。`event: started` で投げる。
+ * Initial SSE event emitted before the graph starts.
+ */
+export function startedEvent(sessionId: string, graphId: string, phase?: string): SseEvent {
+  return phase
+    ? { type: "started", sessionId, graphId, phase }
+    : { type: "started", sessionId, graphId };
+}
+
+/**
+ * フェーズ遷移 SSE。
+ * Phase transition SSE.
+ */
+export function statusEvent(phase: string, message?: string): SseEvent {
+  return message ? { type: "status", phase, message } : { type: "status", phase };
+}
+
+/**
+ * Usage SSE。`ZediChatModel` の usage 計算後に流す。
+ * Usage SSE emitted right after `recordZediUsage`.
+ */
+export function usageEvent(input: {
+  inputTokens: number;
+  outputTokens: number;
+  costUnits: number;
+  usagePercent: number;
+}): SseEvent {
+  return { type: "usage", ...input };
+}
+
+/**
+ * 終了 SSE。`status` で完了 / 中断 / 失敗を区別する。
+ * Terminal SSE describing how the run ended.
+ */
+export function doneEvent(status: "completed" | "interrupted" | "failed"): SseEvent {
+  return { type: "done", status };
+}
+
+/**
+ * エラー SSE。`retryable` は省略可。
+ * Error SSE; `retryable` defaults to undefined.
+ */
+export function errorEvent(message: string, retryable?: boolean): SseEvent {
+  return retryable === undefined
+    ? { type: "error", message }
+    : { type: "error", message, retryable };
+}
+
+/**
+ * LangGraph `streamEvents` から取れる最小限の event 形。本マッパは LangChain の
+ * 詳細型を取り込みすぎないよう、必要なフィールドだけを `unknown` で構造的に
+ * 受け取る。
+ *
+ * Minimal structural type for a LangGraph runtime event so the mapper does not
+ * couple to the full LangChain event union. The runner casts the LangGraph
+ * event to this shape before calling {@link mapLangGraphEvent}.
+ */
+export interface LangGraphRuntimeEvent {
+  event: string;
+  name?: string;
+  data?: unknown;
+  metadata?: Record;
+  tags?: string[];
+}
+
+/**
+ * LangGraph 1 イベント → SseEvent[]。1 入力が複数の SSE event に展開されうるため
+ * 配列で返す。`null` を返したくない設計（呼び出し側のフィルタ条件を 1 箇所に
+ * 集約するため空配列を許容）。
+ *
+ * Returns 0..N {@link SseEvent} for one LangGraph event. Callers iterate and
+ * write each one to the SSE stream. Empty array signals "skip this event".
+ */
+export function mapLangGraphEvent(event: LangGraphRuntimeEvent): SseEvent[] {
+  switch (event.event) {
+    case "on_chat_model_stream":
+      return mapChatModelStream(event);
+    case "on_tool_start":
+      return mapToolStart(event);
+    case "on_tool_end":
+      return mapToolEnd(event);
+    case "on_chain_end":
+      return mapChainEnd(event);
+    default:
+      return [];
+  }
+}
+
+function asRecord(value: unknown): Record | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record)
+    : null;
+}
+
+function mapChatModelStream(event: LangGraphRuntimeEvent): SseEvent[] {
+  const data = asRecord(event.data);
+  if (!data) return [];
+  const chunk = asRecord(data.chunk);
+  if (!chunk) return [];
+  const content = chunk.content;
+  if (typeof content !== "string" || content.length === 0) return [];
+  const node =
+    typeof event.metadata?.langgraph_node === "string"
+      ? (event.metadata.langgraph_node as string)
+      : undefined;
+  return node ? [{ type: "token", node, content }] : [{ type: "token", content }];
+}
+
+function mapToolStart(event: LangGraphRuntimeEvent): SseEvent[] {
+  const tool = event.name;
+  if (!tool) return [];
+  const data = asRecord(event.data);
+  const input = data && asRecord(data.input);
+  return input ? [{ type: "tool_start", tool, input }] : [{ type: "tool_start", tool }];
+}
+
+function mapToolEnd(event: LangGraphRuntimeEvent): SseEvent[] {
+  const tool = event.name;
+  if (!tool) return [];
+  const data = asRecord(event.data);
+  const output = data?.output;
+  const outputLength =
+    typeof output === "string" ? output.length : output === undefined ? undefined : 0;
+  const errorRaw = data?.error;
+  const error =
+    errorRaw instanceof Error
+      ? errorRaw.message
+      : typeof errorRaw === "string"
+        ? errorRaw
+        : undefined;
+  const base = { type: "tool_end" as const, tool };
+  const withLen = outputLength === undefined ? base : { ...base, outputLength };
+  return error ? [{ ...withLen, error }] : [withLen];
+}
+
+function mapChainEnd(event: LangGraphRuntimeEvent): SseEvent[] {
+  // Only emit a status update when the chain end belongs to the top-level
+  // graph (no parent ids in metadata). Nested chain ends would generate noise.
+  // トップレベル graph の終了のみ status を吐く。ネストした chain は無視する。
+  const data = asRecord(event.data);
+  if (!data) return [];
+  const output = asRecord(data.output);
+  if (!output) return [];
+  const phase = typeof output.phase === "string" ? output.phase : undefined;
+  if (!phase) return [];
+  return [{ type: "status", phase }];
+}
diff --git a/server/api/src/app.ts b/server/api/src/app.ts
index 0fff3411..130ba20b 100644
--- a/server/api/src/app.ts
+++ b/server/api/src/app.ts
@@ -43,12 +43,19 @@ import lintRoutes from "./routes/lint.js";
 import activityRoutes from "./routes/activity.js";
 import onboardingRoutes from "./routes/onboarding.js";
 import internalRoutes from "./routes/internal.js";
+import composeSessionRoutes from "./routes/composeSessions.js";
+import { registerStubGraph } from "./agents/registry/stubGraph.js";
 
 /**
  * Creates and configures the Hono API app (routes, CORS, etc.).
  * Hono APIアプリを作成・設定する（ルート・CORS等）。
  */
 export function createApp(): Hono {
+  // Wiki Compose (#948) のスタブグラフを registry に登録する。idempotent。
+  // Register the Wiki Compose P0 smoke-test graph. Idempotent across calls so
+  // hot-reload during dev does not duplicate entries.
+  registerStubGraph();
+
   const app = new Hono();
   const wildcard = isWildcardCors();
   const allowedOrigins = getAllowedOrigins();
@@ -136,6 +143,10 @@ export function createApp(): Hono {
   // Page Snapshots (version history)
   app.route("/api/pages", pageSnapshotRoutes);
 
+  // Wiki Compose sessions (LangGraph runs) — issue #948.
+  // `/api/pages/:pageId/compose-sessions[/:id[/run|/resume]]`
+  app.route("/api/pages", composeSessionRoutes);
+
   // Sync
   app.route("/api/sync/pages", syncPageRoutes);
 
diff --git a/server/api/src/routes/composeSessions.ts b/server/api/src/routes/composeSessions.ts
new file mode 100644
index 00000000..aff6b8fe
--- /dev/null
+++ b/server/api/src/routes/composeSessions.ts
@@ -0,0 +1,400 @@
+/**
+ * `/api/pages/:pageId/compose-sessions` — Wiki Compose session API.
+ *
+ * Wiki Compose の P0 ルートスケルトン。`wiki_compose_sessions` テーブルの CRUD と、
+ * `GraphRunner` 経由でのスタブグラフ実行 (run / resume) を提供する。SSE 形式は
+ * `agents/core/types/sseEvents.ts` の `SseEvent` に従う。
+ *
+ * - `POST   /api/pages/:pageId/compose-sessions`              — Create
+ * - `GET    /api/pages/:pageId/compose-sessions/:id`          — Read
+ * - `POST   /api/pages/:pageId/compose-sessions/:id/run`      — SSE
+ * - `PATCH  /api/pages/:pageId/compose-sessions/:id/resume`   — Resume from interrupt
+ * - `DELETE /api/pages/:pageId/compose-sessions/:id`          — Cancel
+ *
+ * Issue: otomatty/zedi#948
+ */
+import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { streamSSE } from "hono/streaming";
+import { and, eq } from "drizzle-orm";
+import { authRequired } from "../middleware/auth.js";
+import { rateLimit } from "../middleware/rateLimit.js";
+import { assertPageEditAccess, assertPageViewAccess } from "../services/pageAccessService.js";
+import { wikiComposeSessions } from "../schema/wikiComposeSessions.js";
+import type { WikiComposeSessionStatus } from "../schema/wikiComposeSessions.js";
+import { getUserTier } from "../services/subscriptionService.js";
+import { GraphRunner } from "../agents/runner/graphRunner.js";
+import {
+  doneEvent,
+  errorEvent,
+  mapLangGraphEvent,
+  startedEvent,
+  statusEvent,
+  type LangGraphRuntimeEvent,
+} from "../agents/runner/sseMapper.js";
+import { GraphNotRegisteredError, getRegisteredGraph } from "../agents/registry/graphRegistry.js";
+import {
+  assertSupportedBackendP0,
+  UnsupportedBackendError,
+} from "../agents/core/llm/modelFactory.js";
+import { SSE_EVENT_NAMES, type SseEvent } from "../agents/core/types/sseEvents.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../agents/core/types/graphContext.js";
+import { resolveCheckpointerForRun } from "../agents/core/checkpoint/index.js";
+import type { AppEnv } from "../types/index.js";
+
+const app = new Hono();
+
+/**
+ * POST body — create session.
+ *
+ * @property graphId   Registry に登録されたグラフ ID。Registered graph id.
+ * @property backend   Execution backend (省略時は `zedi_managed`)。Defaults to zedi_managed.
+ * @property metadata  自由形式メタデータ。Free-form metadata.
+ */
+interface CreateSessionBody {
+  graphId?: string;
+  backend?: string;
+  metadata?: Record;
+}
+
+interface RunSessionBody {
+  /** 初期入力（最初の messages 等）。任意。 */
+  input?: unknown;
+}
+
+interface ResumeSessionBody {
+  /** Interrupt に渡す再開値。HITL の場合は通常ユーザー応答。 */
+  resume: unknown;
+}
+
+// ── POST / — create ─────────────────────────────────────────────────────────
+app.post("/:pageId/compose-sessions", authRequired, rateLimit(), async (c) => {
+  const pageId = c.req.param("pageId");
+  const userId = c.get("userId");
+  const db = c.get("db");
+
+  await assertPageEditAccess(db, pageId, userId);
+
+  let body: CreateSessionBody;
+  try {
+    body = await c.req.json();
+  } catch {
+    body = {};
+  }
+
+  const graphId =
+    typeof body.graphId === "string" && body.graphId.trim() ? body.graphId.trim() : undefined;
+  if (!graphId) {
+    throw new HTTPException(400, { message: "graphId is required" });
+  }
+  if (!getRegisteredGraph(graphId)) {
+    throw new HTTPException(400, { message: `Unknown graphId: ${graphId}` });
+  }
+
+  let backend: ReturnType;
+  try {
+    backend = assertSupportedBackendP0(body.backend ?? "zedi_managed");
+  } catch (err) {
+    if (err instanceof UnsupportedBackendError) {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+
+  const [row] = await db
+    .insert(wikiComposeSessions)
+    .values({
+      pageId,
+      userId,
+      graphId,
+      backend,
+      status: "pending",
+      metadata: body.metadata ?? null,
+    })
+    .returning();
+  if (!row) throw new HTTPException(500, { message: "Failed to create session" });
+
+  return c.json({ session: row }, 201);
+});
+
+// ── GET /:id — read ─────────────────────────────────────────────────────────
+app.get("/:pageId/compose-sessions/:id", authRequired, async (c) => {
+  const pageId = c.req.param("pageId");
+  const id = c.req.param("id");
+  const userId = c.get("userId");
+  const db = c.get("db");
+
+  await assertPageViewAccess(db, pageId, userId);
+
+  const [row] = await db
+    .select()
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+  if (!row) throw new HTTPException(404, { message: "Session not found" });
+
+  return c.json({ session: row });
+});
+
+// ── POST /:id/run — SSE run ─────────────────────────────────────────────────
+app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (c) => {
+  const pageId = c.req.param("pageId");
+  const id = c.req.param("id");
+  const userId = c.get("userId");
+  const db = c.get("db");
+
+  await assertPageEditAccess(db, pageId, userId);
+
+  const [session] = await db
+    .select()
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+  if (!session) throw new HTTPException(404, { message: "Session not found" });
+
+  if (session.status === "running") {
+    throw new HTTPException(409, { message: "Session is already running" });
+  }
+  if (session.status === "completed" || session.status === "cancelled") {
+    throw new HTTPException(409, { message: `Session is ${session.status}` });
+  }
+
+  let body: RunSessionBody;
+  try {
+    body = await c.req.json();
+  } catch {
+    body = {};
+  }
+
+  const tier = await getUserTier(userId, db);
+  const runner = new GraphRunner();
+
+  // Backend revalidation: row may have been created under a backend that is
+  // no longer permitted (future BYOK downgrade scenarios). Fail fast here.
+  // 行作成後に backend サポートが変わった場合への保険。
+  try {
+    assertSupportedBackendP0(session.backend);
+  } catch (err) {
+    if (err instanceof UnsupportedBackendError) {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+
+  await db
+    .update(wikiComposeSessions)
+    .set({ status: "running" satisfies WikiComposeSessionStatus, updatedAt: new Date() })
+    .where(eq(wikiComposeSessions.id, id));
+
+  return streamSSE(c, async (stream) => {
+    const send = async (ev: SseEvent) => {
+      await stream.writeSSE({ event: ev.type, data: JSON.stringify(ev) });
+    };
+
+    await send(startedEvent(id, session.graphId, session.phase));
+
+    let finalStatus: WikiComposeSessionStatus = "completed";
+    let lastError: string | null = null;
+
+    // `DATABASE_URL` が設定された本番経路では `PostgresSaver` を取得して
+    // checkpoint 保存・再開を有効化する。テスト / CI では未設定なので `false`
+    // を返し、LangGraph の checkpoint 機構を無効化したまま smoke-test で走る。
+    // In production we hand the run a `PostgresSaver` so the LangGraph
+    // checkpointer persists per-thread state; in test / CI environments
+    // `resolveCheckpointerForRun` returns `false` to keep the path runnable
+    // without DDL.
+    const checkpointer = await resolveCheckpointerForRun();
+
+    try {
+      const events = runner.streamEvents(
+        {
+          graphId: session.graphId,
+          checkpointer,
+          context: {
+            threadId: id,
+            sessionId: id,
+            userId,
+            pageId,
+            graphId: session.graphId,
+            backend: assertSupportedBackendP0(session.backend),
+            tier,
+            db,
+            feature: `wiki_compose:${session.graphId}`,
+          },
+        },
+        { kind: "input", value: body.input ?? {} },
+      );
+
+      for await (const raw of events) {
+        const ev = raw as LangGraphRuntimeEvent;
+        for (const mapped of mapLangGraphEvent(ev)) {
+          await send(mapped);
+        }
+      }
+    } catch (err) {
+      if (isInterruptError(err)) {
+        finalStatus = "interrupted";
+        await send({ type: "interrupt", payload: extractInterruptPayload(err) });
+      } else {
+        finalStatus = "failed";
+        lastError = err instanceof Error ? err.message : String(err);
+        await send(errorEvent(lastError));
+      }
+    }
+
+    if (finalStatus === "completed") {
+      await send(statusEvent("completed"));
+    }
+    await send(doneEvent(finalStatus));
+
+    // Both branches of the run loop set finalStatus to a terminal value
+    // (completed / interrupted / failed); always stamp `closedAt`.
+    await db
+      .update(wikiComposeSessions)
+      .set({
+        status: finalStatus,
+        lastError: finalStatus === "failed" ? lastError : null,
+        closedAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(eq(wikiComposeSessions.id, id));
+
+    // Hush unused-import warning when running without exporting names; keeps the
+    // import grouped with the SSE writes for readability.
+    void SSE_EVENT_NAMES;
+    void GRAPH_CONTEXT_CONFIG_KEY;
+  });
+});
+
+// ── PATCH /:id/resume ───────────────────────────────────────────────────────
+app.patch("/:pageId/compose-sessions/:id/resume", authRequired, rateLimit(), async (c) => {
+  const pageId = c.req.param("pageId");
+  const id = c.req.param("id");
+  const userId = c.get("userId");
+  const db = c.get("db");
+
+  await assertPageEditAccess(db, pageId, userId);
+
+  const [session] = await db
+    .select()
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+  if (!session) throw new HTTPException(404, { message: "Session not found" });
+  if (session.status !== "interrupted") {
+    throw new HTTPException(409, { message: "Session is not interrupted" });
+  }
+
+  let body: ResumeSessionBody;
+  try {
+    body = await c.req.json();
+  } catch {
+    throw new HTTPException(400, { message: "Invalid JSON body" });
+  }
+
+  const tier = await getUserTier(userId, db);
+  const runner = new GraphRunner();
+
+  await db
+    .update(wikiComposeSessions)
+    .set({ status: "running", updatedAt: new Date() })
+    .where(eq(wikiComposeSessions.id, id));
+
+  // Resume relies on the checkpointer to fetch the suspended thread; production
+  // routes load `PostgresSaver` here, tests/smoke runs get `false`.
+  // resume は checkpoint から thread を引き直すため、本番では PostgresSaver を渡す。
+  const checkpointer = await resolveCheckpointerForRun();
+
+  let result;
+  try {
+    result = await runner.resume(
+      {
+        graphId: session.graphId,
+        checkpointer,
+        context: {
+          threadId: id,
+          sessionId: id,
+          userId,
+          pageId,
+          graphId: session.graphId,
+          backend: assertSupportedBackendP0(session.backend),
+          tier,
+          db,
+          feature: `wiki_compose:${session.graphId}`,
+        },
+      },
+      body.resume,
+    );
+  } catch (err) {
+    if (err instanceof GraphNotRegisteredError) {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+
+  const status: WikiComposeSessionStatus =
+    result.status === "completed"
+      ? "completed"
+      : result.status === "interrupted"
+        ? "interrupted"
+        : "failed";
+
+  await db
+    .update(wikiComposeSessions)
+    .set({
+      status,
+      lastError: status === "failed" ? (result.error ?? null) : null,
+      closedAt: status === "interrupted" ? null : new Date(),
+      updatedAt: new Date(),
+    })
+    .where(eq(wikiComposeSessions.id, id));
+
+  return c.json({ status, output: result.output ?? null });
+});
+
+// ── DELETE /:id — cancel ────────────────────────────────────────────────────
+app.delete("/:pageId/compose-sessions/:id", authRequired, async (c) => {
+  const pageId = c.req.param("pageId");
+  const id = c.req.param("id");
+  const userId = c.get("userId");
+  const db = c.get("db");
+
+  await assertPageEditAccess(db, pageId, userId);
+
+  const [row] = await db
+    .select({ id: wikiComposeSessions.id, status: wikiComposeSessions.status })
+    .from(wikiComposeSessions)
+    .where(and(eq(wikiComposeSessions.id, id), eq(wikiComposeSessions.pageId, pageId)))
+    .limit(1);
+  if (!row) throw new HTTPException(404, { message: "Session not found" });
+
+  if (row.status === "completed" || row.status === "cancelled") {
+    return c.json({ status: row.status });
+  }
+
+  await db
+    .update(wikiComposeSessions)
+    .set({
+      status: "cancelled" satisfies WikiComposeSessionStatus,
+      closedAt: new Date(),
+      updatedAt: new Date(),
+    })
+    .where(eq(wikiComposeSessions.id, id));
+
+  return c.json({ status: "cancelled" });
+});
+
+function isInterruptError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const name = (err as { name?: unknown }).name;
+  return typeof name === "string" && /Interrupt/.test(name);
+}
+
+function extractInterruptPayload(err: unknown): unknown {
+  if (!err || typeof err !== "object") return undefined;
+  return (
+    (err as { value?: unknown; payload?: unknown }).payload ?? (err as { value?: unknown }).value
+  );
+}
+
+export default app;
diff --git a/server/api/src/schema/index.ts b/server/api/src/schema/index.ts
index 954e2721..c66f876b 100644
--- a/server/api/src/schema/index.ts
+++ b/server/api/src/schema/index.ts
@@ -103,6 +103,12 @@ export {
   type ActivityKind,
   type ActivityActor,
 } from "./activityLog.js";
+export {
+  wikiComposeSessions,
+  type WikiComposeSession,
+  type NewWikiComposeSession,
+  type WikiComposeSessionStatus,
+} from "./wikiComposeSessions.js";
 
 export {
   usersRelations,
diff --git a/server/api/src/schema/wikiComposeSessions.ts b/server/api/src/schema/wikiComposeSessions.ts
new file mode 100644
index 00000000..addc92db
--- /dev/null
+++ b/server/api/src/schema/wikiComposeSessions.ts
@@ -0,0 +1,127 @@
+/**
+ * `wiki_compose_sessions` — メタデータテーブル。1 行 = 1 つの compose 実行。
+ *
+ * Meta-row table for Wiki Compose runs. Each row represents a single user-
+ * initiated compose session for a page; LangGraph's internal `checkpoints*`
+ * tables (owned by `PostgresSaver.setup()`) hold the per-step graph state and
+ * stay outside Drizzle's migration set on purpose.
+ *
+ * The session id is reused as the LangGraph `thread_id`, so callers can
+ * stream / resume by passing the same UUID to both subsystems.
+ *
+ * Issue: #948 (P0 — LangGraph 基盤)
+ */
+import { pgTable, uuid, text, timestamp, index, jsonb } from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+import { users } from "./users.js";
+import { pages } from "./pages.js";
+
+/**
+ * Compose セッションの状態遷移。
+ *
+ * - `pending`     — 行作成済み、run 未開始。Created but never started.
+ * - `running`     — run 中。Streaming or in-flight.
+ * - `interrupted` — interrupt で停止中。resume 可。Paused at an interrupt; resumable.
+ * - `completed`   — 正常終了。Successfully finished.
+ * - `failed`      — 異常終了。Failed with an error.
+ * - `cancelled`   — ユーザーが DELETE で取り消した。User-cancelled.
+ */
+export type WikiComposeSessionStatus =
+  | "pending"
+  | "running"
+  | "interrupted"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+/**
+ * Compose セッションのメタテーブル。
+ * Wiki Compose session metadata table.
+ */
+export const wikiComposeSessions = pgTable(
+  "wiki_compose_sessions",
+  {
+    /**
+     * Session UUID。LangGraph `thread_id` としても再利用する。
+     * Session UUID; also used as the LangGraph `thread_id`.
+     */
+    id: uuid("id").primaryKey().defaultRandom(),
+    /**
+     * 対象ページ ID。
+     * Page id this session writes against.
+     */
+    pageId: uuid("page_id")
+      .notNull()
+      .references(() => pages.id, { onDelete: "cascade" }),
+    /**
+     * 実行ユーザー ID。
+     * Executing user id.
+     */
+    userId: text("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    /**
+     * 登録済みグラフの論理 ID（registry key）。
+     * Registered graph logical id (registry key).
+     */
+    graphId: text("graph_id").notNull(),
+    /**
+     * 直近フェーズ。subgraph 横断の進捗を 1 カラムで表現する軽量フィールド。
+     * Last-known phase identifier (mirrors LangGraph state's `phase` field).
+     */
+    phase: text("phase").notNull().default("init"),
+    /**
+     * 実行 backend。P0 では常に `zedi_managed`。BYOK 対応 (#951) で拡張。
+     * Execution backend; `zedi_managed` only in P0.
+     */
+    backend: text("backend").notNull().default("zedi_managed"),
+    /**
+     * セッション状態。`WikiComposeSessionStatus` を文字列で保持する。
+     * Status of the session as text (see {@link WikiComposeSessionStatus}).
+     */
+    status: text("status").$type().notNull().default("pending"),
+    /**
+     * クライアント由来のメタ情報（モデル ID、初期入力サマリ等）。
+     * Free-form metadata supplied by the client at creation time.
+     */
+    metadata: jsonb("metadata"),
+    /**
+     * 失敗時のエラーメッセージ。失敗状態以外では null。
+     * Last error message; only populated when `status = 'failed'`.
+     */
+    lastError: text("last_error"),
+    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+    /**
+     * 完了時刻。`completed` / `failed` / `cancelled` 遷移時にセット。
+     * Closed-out timestamp; set when leaving an in-flight state.
+     */
+    closedAt: timestamp("closed_at", { withTimezone: true }),
+  },
+  (table) => [
+    /**
+     * `GET /api/pages/:pageId/compose-sessions/:id` の参照経路用インデックス。
+     * Lookup index for fetching a session belonging to a specific page.
+     */
+    index("idx_wiki_compose_sessions_page_id").on(table.pageId),
+    /**
+     * ユーザー単位の一覧用インデックス（管理画面・利用状況集計）。
+     * Per-user listing index for admin / usage dashboards.
+     */
+    index("idx_wiki_compose_sessions_user_id").on(table.userId),
+    /**
+     * "ページごとに新しい順" 列挙用部分複合インデックス。
+     * Partial composite index for "list sessions for a page newest-first".
+     * Restricting to non-terminal statuses keeps the index small for the
+     * common UI query of "what's currently active for this page?".
+     */
+    index("idx_wiki_compose_sessions_page_active_updated")
+      .on(table.pageId, table.updatedAt.desc())
+      .where(sql`${table.status} IN ('pending', 'running', 'interrupted')`),
+  ],
+);
+
+/** Select type. */
+export type WikiComposeSession = typeof wikiComposeSessions.$inferSelect;
+/** Insert type. */
+export type NewWikiComposeSession = typeof wikiComposeSessions.$inferInsert;

From 6f83d609b30c5fd2e950dbfdc5fefb3efef42394 Mon Sep 17 00:00:00 2001
From: "cursor[bot]" <206951365+cursor[bot]@users.noreply.github.com>
Date: Sun, 24 May 2026 18:23:30 +0900
Subject: [PATCH 17/44] fix(api): prevent Wiki Compose sessions stuck in
 running state (#955)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(api): wiki compose P0 — LangGraph エージェント基盤 (#948)

Wiki Compose の P0 基盤として、`server/api/src/agents/` 配下に LangGraph
実行基盤を構築する。後続フェーズ (#949〜) が依存する共通レイヤ。

## 追加

- 依存パッケージ: `@langchain/core`, `@langchain/langgraph`,
  `@langchain/langgraph-checkpoint-postgres`, `@langchain/openai`,
  `@langchain/anthropic`, `@langchain/google-genai`, `zod`
- `agents/core/llm/`:
  - `ZediChatModel` — `BaseChatModel` を継承し、全 LLM 呼び出しを既存
    `callProvider` / `streamProvider` 経由に統一する。`validateModelAccess`
    + `recordUsage` を 1 呼び出しあたり 1 回ずつ通し、`/api/ai/chat` と
    課金経路を共通化する。P0 は backend=`zedi_managed` のみ。
  - `modelFactory` — backend ガード (`assertSupportedBackendP0`) +
    provider API キー解決をまとめる。
  - `usageCallback` — `recordZediUsage` と LangChain `BaseMessage` →
    既存 `AIMessage` への変換ユーティリティ。
- `agents/core/checkpoint/postgresCheckpointer.ts` — `PostgresSaver` の
  プロセスローカルシングルトン。checkpoint テーブルは `setup()` で別管理。
- `agents/core/state/baseState.ts` — 全 subgraph 共通の `BaseState`
  (messages / phase / pageId / userId)。
- `agents/core/tools/` — `web_search` / `wiki_search` / `fetch_article` /
  `image_search` を zod schema + LangGraph tool として登録。P0 は本体スタブ。
- `agents/core/types/` — `ExecutionBackend`, `GraphContext`, `SseEvent`
  の discriminated union。
- `agents/registry/graphRegistry.ts` — `graphId` → factory のマップ。
  P0 動作確認用に `wiki-compose-stub` を登録。
- `agents/runner/`:
  - `GraphRunner` — invoke / streamEvents / resume を一括で受け持つ。
    `thread_id` と `GraphContext` を `configurable` に注入する。
  - `sseMapper` — LangGraph 生イベント → `SseEvent` の純粋関数変換。
- Drizzle: `wiki_compose_sessions` テーブル + migration
  `0031_add_wiki_compose_sessions.sql`。
- Routes `/api/pages/:pageId/compose-sessions`:
  - `POST /` — 行作成 (graphId / backend 検証)
  - `GET /:id` — 取得
  - `POST /:id/run` — SSE 実行
  - `PATCH /:id/resume` — interrupt 再開
  - `DELETE /:id` — キャンセル

## テスト

- `agents/` 配下 5 ファイル (42 件): ZediChatModel の usage 記録経路、
  GraphRunner の registry 解決と Command 渡し、sseMapper の event 変換、
  tools の zod schema と名前安定性、backend ホワイトリスト。
- `routes/composeSessions.test.ts` (10 件): 認可・CRUD・backend ガード。
- 全体: 1306 件 (既存 + 新規)。

* fix(api): prevent compose sessions stuck in running state

Use atomic status claims for run/resume, persist terminal status on SSE
abort, and mark sessions failed when resume throws before completion.

Co-authored-by: akimasa.sugai 

* fix(api): return 400 for unsupported backend on compose resume

Validate session backend before claiming an interrupted session and
map UnsupportedBackendError to HTTP 400, matching POST /run behavior.

Co-authored-by: Cursor 

---------

Co-authored-by: Claude 
Co-authored-by: Cursor Agent 
Co-authored-by: akimasa.sugai 
Co-authored-by: otomatty 
---
 .../__tests__/routes/composeSessions.test.ts  |  72 ++++++++++
 server/api/src/routes/composeSessions.ts      | 130 +++++++++++++-----
 2 files changed, 164 insertions(+), 38 deletions(-)

diff --git a/server/api/src/__tests__/routes/composeSessions.test.ts b/server/api/src/__tests__/routes/composeSessions.test.ts
index cf67f5d7..04284bd2 100644
--- a/server/api/src/__tests__/routes/composeSessions.test.ts
+++ b/server/api/src/__tests__/routes/composeSessions.test.ts
@@ -29,6 +29,10 @@ vi.mock("../../middleware/rateLimit.js", () => ({
   },
 }));
 
+vi.mock("../../services/subscriptionService.js", () => ({
+  getUserTier: async () => "free" as const,
+}));
+
 import { Hono } from "hono";
 import composeSessionRoutes from "../../routes/composeSessions.js";
 import { errorHandler } from "../../middleware/errorHandler.js";
@@ -244,6 +248,74 @@ describe("DELETE /api/pages/:pageId/compose-sessions/:id", () => {
     expect(chains.filter((c) => c.startMethod === "update").length).toBe(0);
   });
 
+  it("returns 400 when resume revalidates an unsupported backend", async () => {
+    const interruptedRow = {
+      id: "sess-resume-backend",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: GRAPH_ID,
+      phase: "init",
+      backend: "byok",
+      status: "interrupted",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app, chains } = createComposeApp([...pageAccessPrefix(), [interruptedRow]]);
+
+    const res = await app.request(
+      `/api/pages/${PAGE_ID}/compose-sessions/sess-resume-backend/resume`,
+      {
+        method: "PATCH",
+        headers: authHeaders(),
+        body: JSON.stringify({ resume: { ok: true } }),
+      },
+    );
+    expect(res.status).toBe(400);
+    expect(chains.filter((c) => c.startMethod === "update").length).toBe(0);
+  });
+
+  it("marks session failed when resume throws GraphNotRegisteredError", async () => {
+    const interruptedRow = {
+      id: "sess-resume-fail",
+      pageId: PAGE_ID,
+      userId: OWNER_ID,
+      graphId: "graph-removed",
+      phase: "init",
+      backend: "zedi_managed",
+      status: "interrupted",
+      metadata: null,
+      lastError: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      closedAt: null,
+    };
+    const { app, chains } = createComposeApp([
+      ...pageAccessPrefix(),
+      [interruptedRow],
+      [interruptedRow], // atomic claim → running
+      undefined, // GraphNotRegisteredError recovery → failed update
+    ]);
+
+    const res = await app.request(
+      `/api/pages/${PAGE_ID}/compose-sessions/sess-resume-fail/resume`,
+      {
+        method: "PATCH",
+        headers: authHeaders(),
+        body: JSON.stringify({ resume: { ok: true } }),
+      },
+    );
+    expect(res.status).toBe(400);
+
+    const failedUpdate = chains
+      .filter((c) => c.startMethod === "update")
+      .map((c) => c.ops.find((op) => op.method === "set")?.args[0] as { status?: string })
+      .find((set) => set?.status === "failed");
+    expect(failedUpdate?.status).toBe("failed");
+  });
+
   it("cancels an active session", async () => {
     const { app, chains } = createComposeApp([
       ...pageAccessPrefix(),
diff --git a/server/api/src/routes/composeSessions.ts b/server/api/src/routes/composeSessions.ts
index aff6b8fe..cd15afd1 100644
--- a/server/api/src/routes/composeSessions.ts
+++ b/server/api/src/routes/composeSessions.ts
@@ -16,7 +16,7 @@
 import { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { streamSSE } from "hono/streaming";
-import { and, eq } from "drizzle-orm";
+import { and, eq, inArray } from "drizzle-orm";
 import { authRequired } from "../middleware/auth.js";
 import { rateLimit } from "../middleware/rateLimit.js";
 import { assertPageEditAccess, assertPageViewAccess } from "../services/pageAccessService.js";
@@ -152,9 +152,6 @@ app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (
     .limit(1);
   if (!session) throw new HTTPException(404, { message: "Session not found" });
 
-  if (session.status === "running") {
-    throw new HTTPException(409, { message: "Session is already running" });
-  }
   if (session.status === "completed" || session.status === "cancelled") {
     throw new HTTPException(409, { message: `Session is ${session.status}` });
   }
@@ -181,31 +178,69 @@ app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (
     throw err;
   }
 
-  await db
+  // Atomically claim the session so concurrent POST /run cannot both pass a
+  // read-then-write race and double-bill LLM usage.
+  const [claimed] = await db
     .update(wikiComposeSessions)
     .set({ status: "running" satisfies WikiComposeSessionStatus, updatedAt: new Date() })
-    .where(eq(wikiComposeSessions.id, id));
+    .where(
+      and(
+        eq(wikiComposeSessions.id, id),
+        eq(wikiComposeSessions.pageId, pageId),
+        inArray(wikiComposeSessions.status, ["pending", "interrupted", "failed"]),
+      ),
+    )
+    .returning();
+  if (!claimed) {
+    throw new HTTPException(409, {
+      message:
+        session.status === "running"
+          ? "Session is already running"
+          : `Session is ${session.status}`,
+    });
+  }
 
   return streamSSE(c, async (stream) => {
     const send = async (ev: SseEvent) => {
       await stream.writeSSE({ event: ev.type, data: JSON.stringify(ev) });
     };
 
-    await send(startedEvent(id, session.graphId, session.phase));
-
-    let finalStatus: WikiComposeSessionStatus = "completed";
+    let finalStatus: WikiComposeSessionStatus = "failed";
     let lastError: string | null = null;
+    let persisted = false;
+
+    const persistSession = async () => {
+      if (persisted) return;
+      persisted = true;
+      await db
+        .update(wikiComposeSessions)
+        .set({
+          status: finalStatus,
+          lastError: finalStatus === "failed" ? lastError : null,
+          closedAt: finalStatus === "interrupted" ? null : new Date(),
+          updatedAt: new Date(),
+        })
+        .where(eq(wikiComposeSessions.id, id));
+    };
+
+    stream.onAbort(() => {
+      if (persisted) return;
+      // Preserve terminal outcomes decided before the client disconnected.
+      if (finalStatus !== "completed" && finalStatus !== "interrupted") {
+        finalStatus = "failed";
+        lastError = lastError ?? "Client disconnected";
+      }
+      void persistSession();
+    });
 
     // `DATABASE_URL` が設定された本番経路では `PostgresSaver` を取得して
     // checkpoint 保存・再開を有効化する。テスト / CI では未設定なので `false`
     // を返し、LangGraph の checkpoint 機構を無効化したまま smoke-test で走る。
-    // In production we hand the run a `PostgresSaver` so the LangGraph
-    // checkpointer persists per-thread state; in test / CI environments
-    // `resolveCheckpointerForRun` returns `false` to keep the path runnable
-    // without DDL.
     const checkpointer = await resolveCheckpointerForRun();
 
     try {
+      await send(startedEvent(id, session.graphId, session.phase));
+
       const events = runner.streamEvents(
         {
           graphId: session.graphId,
@@ -231,6 +266,8 @@ app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (
           await send(mapped);
         }
       }
+
+      finalStatus = "completed";
     } catch (err) {
       if (isInterruptError(err)) {
         finalStatus = "interrupted";
@@ -240,29 +277,18 @@ app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (
         lastError = err instanceof Error ? err.message : String(err);
         await send(errorEvent(lastError));
       }
-    }
+    } finally {
+      if (finalStatus === "completed") {
+        await send(statusEvent("completed"));
+      }
+      await send(doneEvent(finalStatus));
+      await persistSession();
 
-    if (finalStatus === "completed") {
-      await send(statusEvent("completed"));
+      // Hush unused-import warning when running without exporting names; keeps the
+      // import grouped with the SSE writes for readability.
+      void SSE_EVENT_NAMES;
+      void GRAPH_CONTEXT_CONFIG_KEY;
     }
-    await send(doneEvent(finalStatus));
-
-    // Both branches of the run loop set finalStatus to a terminal value
-    // (completed / interrupted / failed); always stamp `closedAt`.
-    await db
-      .update(wikiComposeSessions)
-      .set({
-        status: finalStatus,
-        lastError: finalStatus === "failed" ? lastError : null,
-        closedAt: new Date(),
-        updatedAt: new Date(),
-      })
-      .where(eq(wikiComposeSessions.id, id));
-
-    // Hush unused-import warning when running without exporting names; keeps the
-    // import grouped with the SSE writes for readability.
-    void SSE_EVENT_NAMES;
-    void GRAPH_CONTEXT_CONFIG_KEY;
   });
 });
 
@@ -295,14 +321,32 @@ app.patch("/:pageId/compose-sessions/:id/resume", authRequired, rateLimit(), asy
   const tier = await getUserTier(userId, db);
   const runner = new GraphRunner();
 
-  await db
+  try {
+    assertSupportedBackendP0(session.backend);
+  } catch (err) {
+    if (err instanceof UnsupportedBackendError) {
+      throw new HTTPException(400, { message: err.message });
+    }
+    throw err;
+  }
+
+  const [claimed] = await db
     .update(wikiComposeSessions)
     .set({ status: "running", updatedAt: new Date() })
-    .where(eq(wikiComposeSessions.id, id));
+    .where(
+      and(
+        eq(wikiComposeSessions.id, id),
+        eq(wikiComposeSessions.pageId, pageId),
+        eq(wikiComposeSessions.status, "interrupted"),
+      ),
+    )
+    .returning();
+  if (!claimed) {
+    throw new HTTPException(409, { message: "Session is not interrupted" });
+  }
 
   // Resume relies on the checkpointer to fetch the suspended thread; production
   // routes load `PostgresSaver` here, tests/smoke runs get `false`.
-  // resume は checkpoint から thread を引き直すため、本番では PostgresSaver を渡す。
   const checkpointer = await resolveCheckpointerForRun();
 
   let result;
@@ -326,7 +370,17 @@ app.patch("/:pageId/compose-sessions/:id/resume", authRequired, rateLimit(), asy
       body.resume,
     );
   } catch (err) {
-    if (err instanceof GraphNotRegisteredError) {
+    const message = err instanceof Error ? err.message : String(err);
+    await db
+      .update(wikiComposeSessions)
+      .set({
+        status: "failed",
+        lastError: message,
+        closedAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(eq(wikiComposeSessions.id, id));
+    if (err instanceof GraphNotRegisteredError || err instanceof UnsupportedBackendError) {
       throw new HTTPException(400, { message: err.message });
     }
     throw err;

From 779c1f5ff9e7718adee8518a4d515c5d09bdae9a Mon Sep 17 00:00:00 2001
From: Akimasa Sugai <119780981+otomatty@users.noreply.github.com>
Date: Sun, 24 May 2026 21:14:49 +0900
Subject: [PATCH 18/44] feat: implement Wiki Compose research loop subgraph
 (#949) (#956)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(api): Wiki Compose P1 — researchLoopSubgraph (#949)

Implements the autonomous research-loop subgraph for Wiki Compose on top
of the P0 LangGraph scaffold (#948). Backend only — frontend
ResearchSection / ActivitySection are deferred to P2 (#950).

## researchLoopSubgraph

`plan_queries → (web_search ∥ wiki_search) → fetch_articles →
evaluate_sufficiency → [refine_queries → loop] × N → compile_batch →
human_review_research (interrupt) → END`

Exit when `score >= 0.75` OR `iteration >= maxIterations` (default 3,
clamped 1..5). HITL via LangGraph 1.x `interrupt()`; resume payload
`{ approvedSourceIds, rejectedSourceIds?, note? }` validated by
`researchResumeSchema` and projected into `approvedResearch` /
`rejectedResearch`. Additional research re-runs the graph on a fresh
session with `{ kind: "additional_research", instruction,
carryOverApprovedIds }` input (no new route).

## Tools (replaces stubs)

- `wikiSearchTool` — reads `db`/`userId`/`userEmail` from `GraphContext`
  and calls new `searchUserWikiPages` service (extracted from
  `routes/search.ts` preserving the `scope=shared` SQL exactly).
- `fetchArticleTool` — wraps `extractArticleFromUrl` with the same
  `isClipUrlAllowedAfterDns` SSRF guard `clipServerFetch` uses; per-URL
  errors return `{ ok:false, error }` so one bad URL never aborts the
  loop.
- `webSearchTool` — resolves cheapest OpenAI/Google model via
  `resolveWebSearchModelId` (env override + `ai_models` query), then
  builds `ZediChatModel` with `useWebSearch` / `useGoogleSearch` for
  structured output. Documented fallback: no managed search model →
  `{ ok:true, results:[], note:"web_search_unavailable" }`.

## P0 surface additions (additive, non-breaking)

- `ZediChatModel.extraProviderOptions` pass-through for provider knobs
  (used by `webSearchTool`).
- `GraphContext.userEmail` for `wikiSearchService`'s domain predicate.
- 3 new SSE events: `research_iteration`, `research_evaluation`,
  `research_batch` dispatched via `dispatchCustomEvent`, surfaced by a
  new `on_custom_event` branch in `sseMapper.mapLangGraphEvent`.

## P0 bug fix (interrupt detection)

LangGraph ≥ 1.x surfaces interrupts on the result state as a
`__interrupt__: Interrupt[]` array, NOT as a thrown error.
`GraphRunner.invoke` now detects this; `sseMapper.mapChainEnd` converts
it to a wire `SseInterruptEvent`; the route flips `finalStatus` to
`"interrupted"` on any emitted interrupt event. Legacy throw path is
kept for forward-compat / version skew.

## Composition

- `recursionLimit: 60` for `wiki-compose-research` (≈5 iterations ×
  ~6 nodes); other graphs keep the default 25.
- `registerResearchLoopGraph()` called from `app.ts` alongside
  `registerStubGraph()`.

## Tests (24 new)

- `researchGraph.{conditional,loop,interrupt,resume,modelGuard}` cover
  all #949 acceptance criteria (autonomous loop to maxIterations,
  conditional edge, interrupt position, resume → approvedResearch,
  re-run input shape, every LLM via `createZediChatModel`).
- `tools/{wikiSearch,webSearch,fetchArticle}` for per-tool envelopes,
  SSRF guard, Anthropic fallback.
- `nodes/compileBatch` for exit-reason derivation.
- `services/wikiSearchService` for the extracted page-search service.

`pnpm vitest run` — 1333 passed (109 files). `bunx tsc --noEmit` clean.

Closes #949.

* refactor(api/agents): inline web-search model resolver next to its caller

Cleanup follow-up to the initial #949 commit, no behaviour change.

- Replace lazy `await import()` inside `detectProviderForModelId` with
  top-level imports from `drizzle-orm` + the `aiModels` schema; the
  schema layer is leaf-level so there's no circular-dep risk.
- Move `resolveWebSearchModelId` from
  `agents/subgraphs/research/nodes/shared/` to `agents/core/tools/`
  next to its only consumer (`webSearch.ts`). Removes the backward
  directional dependency from `core` → `subgraphs`.

`bunx tsc --noEmit` clean; 24 research-loop tests + 65 agents tests
still pass.

* fix(api/agents): address PR #956 review feedback

Two substantive bugs surfaced by the automated PR review:

## codex P1 — additional-research input contract was broken

The documented `body.input = { kind: "additional_research", ... }` shape
never reached `plan_queries`: LangGraph's strict state schema drops top-
level input keys that have no annotation, so `kind` / `instruction` /
`carryOverApprovedIds` silently vanished and re-runs behaved like a
normal initial run.

Fix:

- Add `additionalRequest: AdditionalResearchRequest | null` to
  `ResearchLoopState` (and `types.ts`); reducer is `(prev, next) =>
   next ?? prev`, default `null`.
- The route now translates `{ kind: "additional_research", ... }` into
  `{ additionalRequest: {...} }` before passing to the graph
  (`translateGraphInput` in `composeSessions.ts`); other graph ids pass
  through unchanged. Public client contract is unchanged.
- `plan_queries` reads `state.additionalRequest` (not `messages[0]`)
  and clears it to `null` after consumption so a defensive re-plan in
  the same session doesn't loop on the same instruction.

## codex P2 + gemini #1/#2/#4 — web↔fetched dedup was bogus

The JSDoc claimed "in-place upgrade from `kind:web` to `kind:fetched`",
but `web:` and `fetched:` were distinct ids so
the id-keyed reducer kept both rows. After a redirect (trailing slash /
canonical host change), they wouldn't even agree on URL, splitting the
same article into two state rows and re-fetching across iterations.

Fix:

- Unified id scheme `src:` for web AND fetched.
  Fetched rows carry the source row's id over instead of minting a new
  one, so the reducer (`mergeSourcesById`) overwrites the web row in
  place — matching the JSDoc contract.
- New optional `Source.finalUrl` carries the redirect-resolved URL for
  display / citation; `Source.url` stays equal to the original so the
  id stays stable across iterations.
- `fetchArticles` no longer maintains a separate `fetchedUrls` set; the
  reducer-level dedup is sufficient now that ids match.

## gemini #3 — evaluateSufficiency maxTokens 512 → 1024

512 was tight for a structured `{ score, rationale, missingAspects[] }`
response when the LLM verbose-explained low-score iterations; bumped to
1024 to keep JSON from truncating mid-array.

## Tests

- New: `nodes/planQueries.test.ts` (3 tests) — exercises the
  `additionalRequest` consumption and `maxIterations` clamping.
- Updated existing tests' Source ids from `web:` to `src:`.
- All 1336 tests pass (110 files); `tsc --noEmit` and `biome` clean.

* style: prettier --write on Wiki Compose P1 files

CI Lint job ran prettier --check across the repo and flagged 20 files
introduced by #949 / the merge of develop's #955 fix. Re-formatted with
prettier; no behaviour change.

Format-check, lint, and docs:check-pairs all pass locally; agents +
services + routes tests still pass (860/860).

* fix(api/agents): address PR #956 review feedback (round 3)

## Critical (coderabbit)

composeSessions.ts:357 unconditionally set finalStatus = "completed"
after the SSE stream drained, silently overwriting the "interrupted"
state set inside the for-await loop. Interrupted sessions were therefore
persisted as completed (closedAt set), breaking the resume path. The
bug was a regression from the merge of develop's #955 fix, which moved
the default initialiser without updating this branch.

Fix: guard the completion promotion with `finalStatus !== "interrupted"`.

## Major (coderabbit) — resolveWebSearchModel tier filter

The resolver could pick a tier-inaccessible model (or an env override
that the caller's tier could not use), which then exploded inside
`createZediChatModel` and surfaced as an error envelope instead of the
documented graceful "web_search_unavailable" path.

Fix: add a `UserTier` parameter and apply `tierRequired = "free"` for
free users. Validate env overrides through the same DB filter before
returning — if the override is inactive or tier-blocked, fall through
to the standard lookup.

## Major (coderabbit) — TSDoc on exported node functions

Added function-level TSDoc to all 7 exported research-loop node
functions per repo guidelines: `compileBatch`, `evaluateSufficiency`,
`fetchArticles`, `humanReviewResearch`, `refineQueries`, `webSearch`,
`wikiSearch`. Each documents its purpose, params, return shape, and
notable side-effects / thrown errors.

## Minor (coderabbit) — getGraphContext field check

Added a minimal field-presence check (`userId`, `db`, `feature`) so a
malformed context fails loudly at the call site rather than deep inside
`recordUsage`. Avoided pulling in Zod for a single-producer contract.

## Skipped with reason

- gemini #2 (evaluateSufficiency dedup web/fetched in prompt): already
  resolved by the unified `src:` id scheme — the state reducer
  dedupes upstream, so evaluate_sufficiency never sees both kinds for
  the same URL.
- gemini #4 (state.ts JSDoc claim about in-place upgrade): already
  resolved by the same id refactor in this round of fixes.

## Verification

- `bunx tsc --noEmit` clean.
- Agents + services + composeSessions tests: 84/84 pass.
- `bun run format:check` / `bun run lint` (0 errors) / `docs:check-pairs` all green.

---------

Co-authored-by: Claude 
---
 .../__tests__/agents/core/tools/tools.test.ts |  40 +--
 .../agents/runner/graphRunner.test.ts         |   1 +
 .../research/nodes/compileBatch.test.ts       |  86 +++++++
 .../research/nodes/planQueries.test.ts        | 120 +++++++++
 .../researchGraph.conditional.test.ts         |  93 +++++++
 .../research/researchGraph.interrupt.test.ts  | 144 +++++++++++
 .../research/researchGraph.loop.test.ts       | 241 ++++++++++++++++++
 .../research/researchGraph.modelGuard.test.ts | 169 ++++++++++++
 .../research/researchGraph.resume.test.ts     | 238 +++++++++++++++++
 .../research/tools/fetchArticle.test.ts       |  95 +++++++
 .../research/tools/webSearch.test.ts          |  84 ++++++
 .../research/tools/wikiSearch.test.ts         | 110 ++++++++
 .../services/wikiSearchService.test.ts        | 115 +++++++++
 .../api/src/agents/core/llm/modelFactory.ts   |   5 +-
 .../api/src/agents/core/llm/zediChatModel.ts  |  38 ++-
 .../api/src/agents/core/tools/fetchArticle.ts |  75 +++++-
 .../core/tools/resolveWebSearchModel.ts       | 103 ++++++++
 server/api/src/agents/core/tools/webSearch.ts | 230 +++++++++++++++--
 .../api/src/agents/core/tools/wikiSearch.ts   |  82 ++++--
 .../api/src/agents/core/types/graphContext.ts |   5 +
 server/api/src/agents/core/types/index.ts     |   3 +
 server/api/src/agents/core/types/sseEvents.ts |  68 ++++-
 server/api/src/agents/index.ts                |  18 ++
 server/api/src/agents/runner/graphRunner.ts   |  31 ++-
 server/api/src/agents/runner/sseMapper.ts     | 111 +++++++-
 .../src/agents/subgraphs/research/index.ts    |  28 ++
 .../subgraphs/research/nodes/compileBatch.ts  |  59 +++++
 .../research/nodes/evaluateSufficiency.ts     | 115 +++++++++
 .../subgraphs/research/nodes/fetchArticles.ts | 109 ++++++++
 .../research/nodes/humanReviewResearch.ts     |  79 ++++++
 .../agents/subgraphs/research/nodes/index.ts  |  16 ++
 .../subgraphs/research/nodes/planQueries.ts   | 155 +++++++++++
 .../subgraphs/research/nodes/refineQueries.ts |  92 +++++++
 .../nodes/shared/dispatchSseCustom.ts         |  58 +++++
 .../research/nodes/shared/getGraphContext.ts  |  48 ++++
 .../subgraphs/research/nodes/webSearch.ts     |  72 ++++++
 .../subgraphs/research/nodes/wikiSearch.ts    |  74 ++++++
 .../subgraphs/research/researchGraph.ts       | 107 ++++++++
 .../agents/subgraphs/research/resumeSchema.ts |  33 +++
 .../src/agents/subgraphs/research/state.ts    | 122 +++++++++
 .../src/agents/subgraphs/research/types.ts    | 157 ++++++++++++
 server/api/src/app.ts                         |  11 +-
 server/api/src/routes/composeSessions.ts      | 112 +++++++-
 server/api/src/routes/search.ts               | 152 +++--------
 server/api/src/services/wikiSearchService.ts  | 175 +++++++++++++
 45 files changed, 3873 insertions(+), 206 deletions(-)
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/nodes/compileBatch.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/nodes/planQueries.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/researchGraph.conditional.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/researchGraph.interrupt.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/researchGraph.loop.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/researchGraph.modelGuard.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/researchGraph.resume.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/tools/fetchArticle.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/tools/webSearch.test.ts
 create mode 100644 server/api/src/__tests__/agents/subgraphs/research/tools/wikiSearch.test.ts
 create mode 100644 server/api/src/__tests__/services/wikiSearchService.test.ts
 create mode 100644 server/api/src/agents/core/tools/resolveWebSearchModel.ts
 create mode 100644 server/api/src/agents/subgraphs/research/index.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/compileBatch.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/evaluateSufficiency.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/fetchArticles.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/humanReviewResearch.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/index.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/planQueries.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/refineQueries.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/shared/dispatchSseCustom.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/shared/getGraphContext.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/webSearch.ts
 create mode 100644 server/api/src/agents/subgraphs/research/nodes/wikiSearch.ts
 create mode 100644 server/api/src/agents/subgraphs/research/researchGraph.ts
 create mode 100644 server/api/src/agents/subgraphs/research/resumeSchema.ts
 create mode 100644 server/api/src/agents/subgraphs/research/state.ts
 create mode 100644 server/api/src/agents/subgraphs/research/types.ts
 create mode 100644 server/api/src/services/wikiSearchService.ts

diff --git a/server/api/src/__tests__/agents/core/tools/tools.test.ts b/server/api/src/__tests__/agents/core/tools/tools.test.ts
index d857467b..63ec45f7 100644
--- a/server/api/src/__tests__/agents/core/tools/tools.test.ts
+++ b/server/api/src/__tests__/agents/core/tools/tools.test.ts
@@ -1,11 +1,14 @@
 /**
  * Tools (web_search / wiki_search / fetch_article / image_search) のスキーマと
- * `bindTools` 互換性を確認するテスト。本実装は #949 以降だが、スキーマ・名前が
- * P0 段階で固まっていることをテストで担保する。
+ * `bindTools` 互換性を確認するテスト。`wiki_search` / `web_search` /
+ * `fetch_article` は #949 で本実装に置き換わったため、sentinel 応答テストは
+ * 削除し、graph context 欠落時のエラー shape（JSON envelope `{ ok:false }`）を
+ * 確認する単体テストに差し替えた。詳細な挙動は
+ * `__tests__/agents/subgraphs/research/tools/*.test.ts` 側で検証する。
  *
- * Pin the public surface of the shared tool set so P1+ subgraph PRs cannot
- * silently rename or restructure a tool. Behaviour itself is stubbed and not
- * asserted here beyond "returns the sentinel string".
+ * Pin the public surface of the shared tool set so subgraph PRs cannot silently
+ * rename or restructure a tool. Stub `image_search` still returns a sentinel;
+ * other tools return JSON envelopes (parsed back by their caller nodes).
  */
 import { describe, expect, it } from "vitest";
 import {
@@ -79,21 +82,22 @@ describe("SHARED_TOOLS", () => {
   });
 });
 
-describe("stub tool bodies", () => {
-  it("web_search returns the not-implemented sentinel", async () => {
-    const out = (await webSearchTool.invoke({ query: "ripgrep" })) as unknown;
-    expect(typeof out).toBe("string");
-    expect(out).toMatch(/WEB_SEARCH_NOT_IMPLEMENTED/);
+describe("tool bodies — minimal envelopes", () => {
+  it("wiki_search returns a JSON envelope and reports missing context", async () => {
+    const raw = (await wikiSearchTool.invoke({ query: "ripgrep" })) as unknown;
+    expect(typeof raw).toBe("string");
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("missing_graph_context");
   });
-  it("wiki_search returns the not-implemented sentinel", async () => {
-    const out = (await wikiSearchTool.invoke({ query: "ripgrep" })) as unknown;
-    expect(out).toMatch(/WIKI_SEARCH_NOT_IMPLEMENTED/);
+  it("web_search returns a JSON envelope and reports missing context", async () => {
+    const raw = (await webSearchTool.invoke({ query: "ripgrep" })) as unknown;
+    expect(typeof raw).toBe("string");
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("missing_graph_context");
   });
-  it("fetch_article returns the not-implemented sentinel", async () => {
-    const out = (await fetchArticleTool.invoke({ url: "https://example.com" })) as unknown;
-    expect(out).toMatch(/FETCH_ARTICLE_NOT_IMPLEMENTED/);
-  });
-  it("image_search returns the not-implemented sentinel", async () => {
+  it("image_search still returns the not-implemented sentinel (#949 scope)", async () => {
     const out = (await imageSearchTool.invoke({ query: "cat" })) as unknown;
     expect(out).toMatch(/IMAGE_SEARCH_NOT_IMPLEMENTED/);
   });
diff --git a/server/api/src/__tests__/agents/runner/graphRunner.test.ts b/server/api/src/__tests__/agents/runner/graphRunner.test.ts
index 9eeef85c..3538248a 100644
--- a/server/api/src/__tests__/agents/runner/graphRunner.test.ts
+++ b/server/api/src/__tests__/agents/runner/graphRunner.test.ts
@@ -30,6 +30,7 @@ function fakeContext(): GraphContext {
     tier: "free",
     db: {} as Database,
     feature: "test",
+    userEmail: null,
   };
 }
 
diff --git a/server/api/src/__tests__/agents/subgraphs/research/nodes/compileBatch.test.ts b/server/api/src/__tests__/agents/subgraphs/research/nodes/compileBatch.test.ts
new file mode 100644
index 00000000..005c3cb9
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/nodes/compileBatch.test.ts
@@ -0,0 +1,86 @@
+/**
+ * `compileBatch` unit tests. Pure projection node; no LLM. We verify:
+ * - `exitReason` = "score_threshold" when score >= 0.75.
+ * - `exitReason` = "max_iterations" otherwise.
+ * - Batch fields are populated from state.
+ * - `dispatchCustomEvent` is called via the runnable config.
+ */
+import { describe, expect, it, vi } from "vitest";
+
+// The dispatch helper requires a proper LangChain callback manager which we
+// don't set up here (`compileBatch` is a pure projection). Stub it so the
+// node can dispatch into a no-op without a real callback runtime.
+// dispatch ヘルパは callback manager 必須なので test では no-op に差し替える。
+const { dispatchResearchBatch } = vi.hoisted(() => ({
+  dispatchResearchBatch: vi.fn(async () => undefined),
+}));
+vi.mock("../../../../../agents/subgraphs/research/nodes/shared/dispatchSseCustom.js", () => ({
+  dispatchResearchBatch,
+  dispatchResearchEvaluation: vi.fn(),
+  dispatchResearchIteration: vi.fn(),
+}));
+
+import { compileBatch } from "../../../../../agents/subgraphs/research/nodes/compileBatch.js";
+import type { ResearchLoopStateType } from "../../../../../agents/subgraphs/research/state.js";
+import type { ResearchBatch } from "../../../../../agents/subgraphs/research/types.js";
+
+function state(overrides: Partial): ResearchLoopStateType {
+  return {
+    messages: [],
+    phase: "research:evaluated",
+    pageId: "page-1",
+    userId: "user-1",
+    iteration: 2,
+    maxIterations: 3,
+    queries: [{ id: "q1", query: "q", channels: ["web"] }],
+    pendingSources: [
+      { id: "src:a", kind: "web", title: "A", url: "https://a/" },
+      { id: "src:b", kind: "web", title: "B", url: "https://b/" },
+    ],
+    lastEvaluation: null,
+    exitReason: null,
+    batches: [],
+    approvedResearch: [],
+    rejectedResearch: [],
+    additionalRequest: null,
+    ...overrides,
+  };
+}
+
+describe("compileBatch", () => {
+  it("uses score_threshold when last score >= 0.75", async () => {
+    const dispatcher = vi.fn();
+    const config = {
+      configurable: { callbacks: undefined },
+      callbacks: { handlers: [], inheritableHandlers: [], dispatchCustomEvent: dispatcher },
+    };
+    const update = await compileBatch(
+      state({ lastEvaluation: { score: 0.85, rationale: "ok", missingAspects: [] } }),
+      // Loose config type — node only reads callback runtime, which LangGraph
+      // wires through the surrounding `streamEvents` / `invoke` call.
+      config as never,
+    );
+    expect(update.exitReason).toBe("score_threshold");
+    const batches = update.batches as ResearchBatch[] | undefined;
+    expect(batches?.length).toBe(1);
+    expect(batches?.[0]?.sources.length).toBe(2);
+    expect(batches?.[0]?.iteration).toBe(2);
+  });
+
+  it("uses max_iterations when no eval or score below threshold", async () => {
+    const update = await compileBatch(
+      state({ lastEvaluation: { score: 0.5, rationale: "weak", missingAspects: ["x"] } }),
+      { configurable: {} } as never,
+    );
+    expect(update.exitReason).toBe("max_iterations");
+  });
+
+  it("handles null evaluation gracefully", async () => {
+    const update = await compileBatch(state({ lastEvaluation: null }), {
+      configurable: {},
+    } as never);
+    expect(update.exitReason).toBe("max_iterations");
+    const batches = update.batches as ResearchBatch[] | undefined;
+    expect(batches?.[0]?.evaluation).toBeNull();
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/nodes/planQueries.test.ts b/server/api/src/__tests__/agents/subgraphs/research/nodes/planQueries.test.ts
new file mode 100644
index 00000000..17b89978
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/nodes/planQueries.test.ts
@@ -0,0 +1,120 @@
+/**
+ * `planQueries` unit tests. Focus on the additional-research detection branch
+ * (codex review #956 P1): the node MUST read from `state.additionalRequest`
+ * (not `state.messages[0]`) so the documented `body.input.kind` translation
+ * by the route layer survives.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { createZediChatModel } = vi.hoisted(() => ({ createZediChatModel: vi.fn() }));
+
+vi.mock("../../../../../agents/core/llm/modelFactory.js", async () => {
+  const actual = await vi.importActual<
+    typeof import("../../../../../agents/core/llm/modelFactory.js")
+  >("../../../../../agents/core/llm/modelFactory.js");
+  return {
+    ...actual,
+    createZediChatModel: (...args: unknown[]) =>
+      createZediChatModel(...(args as Parameters)),
+  };
+});
+
+// Stub dispatch helpers so the node can run without a real callback manager.
+vi.mock("../../../../../agents/subgraphs/research/nodes/shared/dispatchSseCustom.js", () => ({
+  dispatchResearchIteration: vi.fn(async () => undefined),
+  dispatchResearchEvaluation: vi.fn(async () => undefined),
+  dispatchResearchBatch: vi.fn(async () => undefined),
+}));
+
+import { planQueries } from "../../../../../agents/subgraphs/research/nodes/planQueries.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../../../../../agents/core/types/graphContext.js";
+import type { GraphContext } from "../../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../../types/index.js";
+import type { ResearchLoopStateType } from "../../../../../agents/subgraphs/research/state.js";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "t",
+    sessionId: "t",
+    userId: "u-1",
+    pageId: "p-1",
+    graphId: "wiki-compose-research",
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+function state(overrides: Partial): ResearchLoopStateType {
+  return {
+    messages: [],
+    phase: "init",
+    pageId: "p-1",
+    userId: "u-1",
+    iteration: 0,
+    maxIterations: 3,
+    queries: [],
+    pendingSources: [],
+    lastEvaluation: null,
+    exitReason: null,
+    batches: [],
+    approvedResearch: [],
+    rejectedResearch: [],
+    additionalRequest: null,
+    ...overrides,
+  };
+}
+
+function fakeModel(structuredReturn: () => Promise) {
+  const runnable = { invoke: vi.fn(async () => structuredReturn()) };
+  return { withStructuredOutput: vi.fn(() => runnable) };
+}
+
+beforeEach(() => {
+  createZediChatModel.mockReset();
+  createZediChatModel.mockResolvedValue(
+    fakeModel(async () => ({
+      queries: [{ query: "q1", channels: ["web"] }],
+    })),
+  );
+});
+afterEach(() => {
+  createZediChatModel.mockReset();
+});
+
+describe("planQueries — additional research detection", () => {
+  const config = { configurable: { [GRAPH_CONTEXT_CONFIG_KEY]: fakeContext() } };
+
+  it("clamps maxIterations to 1..5 (default 3)", async () => {
+    const update = await planQueries(state({ maxIterations: 99 }), config as never);
+    expect(update.maxIterations).toBe(5);
+  });
+
+  it("consumes state.additionalRequest and seeds carried-over sources", async () => {
+    const update = await planQueries(
+      state({
+        additionalRequest: {
+          instruction: "go deeper on benchmarks",
+          carryOverApprovedIds: ["src:abc", "wiki:p-7"],
+        },
+      }),
+      config as never,
+    );
+    // additionalRequest is cleared after first read so a defensive re-plan
+    // does not loop on the same instruction.
+    expect(update.additionalRequest).toBeNull();
+    // pendingSources seeded from carryOverApprovedIds (id-prefix → kind).
+    expect(update.pendingSources).toEqual([
+      expect.objectContaining({ id: "src:abc", kind: "fetched" }),
+      expect.objectContaining({ id: "wiki:p-7", kind: "wiki" }),
+    ]);
+  });
+
+  it("does NOT reset pendingSources when there is no additionalRequest", async () => {
+    const update = await planQueries(state({ additionalRequest: null }), config as never);
+    // Standard initial run leaves pendingSources untouched.
+    expect(update.pendingSources).toBeUndefined();
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.conditional.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.conditional.test.ts
new file mode 100644
index 00000000..ac8fa778
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.conditional.test.ts
@@ -0,0 +1,93 @@
+/**
+ * `shouldRefine` 純粋関数の table-driven テスト。issue #949 受け入れ条件 #2:
+ * 「conditional edge (refine vs compile) の単体テストがある」。
+ *
+ * Table-driven tests for `shouldRefine` — the conditional edge predicate after
+ * `evaluate_sufficiency`. We avoid spinning up a `StateGraph` here because the
+ * predicate is pure; the wiring is exercised by the loop / interrupt tests.
+ */
+import { describe, expect, it } from "vitest";
+import { shouldRefine } from "../../../../agents/subgraphs/research/researchGraph.js";
+import type { ResearchLoopStateType } from "../../../../agents/subgraphs/research/state.js";
+
+function state(overrides: Partial): ResearchLoopStateType {
+  return {
+    messages: [],
+    phase: "research:evaluated",
+    pageId: "page-1",
+    userId: "user-1",
+    iteration: 1,
+    maxIterations: 3,
+    queries: [],
+    pendingSources: [],
+    lastEvaluation: null,
+    exitReason: null,
+    batches: [],
+    approvedResearch: [],
+    rejectedResearch: [],
+    additionalRequest: null,
+    ...overrides,
+  };
+}
+
+describe("shouldRefine", () => {
+  it("compiles when score >= 0.75 even if iterations remain", () => {
+    expect(
+      shouldRefine(
+        state({
+          iteration: 1,
+          maxIterations: 5,
+          lastEvaluation: { score: 0.75, rationale: "ok", missingAspects: [] },
+        }),
+      ),
+    ).toBe("compile");
+  });
+
+  it("compiles when score is high above the threshold", () => {
+    expect(
+      shouldRefine(
+        state({
+          iteration: 1,
+          maxIterations: 5,
+          lastEvaluation: { score: 0.95, rationale: "great", missingAspects: [] },
+        }),
+      ),
+    ).toBe("compile");
+  });
+
+  it("refines when score is below threshold and iterations remain", () => {
+    expect(
+      shouldRefine(
+        state({
+          iteration: 1,
+          maxIterations: 3,
+          lastEvaluation: { score: 0.5, rationale: "weak", missingAspects: ["x"] },
+        }),
+      ),
+    ).toBe("refine");
+  });
+
+  it("compiles at the hard iteration cap even if score is low", () => {
+    expect(
+      shouldRefine(
+        state({
+          iteration: 3,
+          maxIterations: 3,
+          lastEvaluation: { score: 0.4, rationale: "weak", missingAspects: ["x", "y"] },
+        }),
+      ),
+    ).toBe("compile");
+  });
+
+  it("compiles past the cap (defence against off-by-one)", () => {
+    expect(shouldRefine(state({ iteration: 4, maxIterations: 3 }))).toBe("compile");
+  });
+
+  it("refines when there's no evaluation yet and iterations remain", () => {
+    // Defensive: if evaluate_sufficiency hasn't run, treat as "not enough yet".
+    // evaluation 未走の保険 — まだ充足してないとみなす。
+    expect(shouldRefine(state({ iteration: 0, maxIterations: 3, lastEvaluation: null }))).toBe(
+      "refine",
+    );
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.interrupt.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.interrupt.test.ts
new file mode 100644
index 00000000..aadfb110
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.interrupt.test.ts
@@ -0,0 +1,144 @@
+/**
+ * issue #949 受け入れ条件 #3:
+ * 「ループ終了後 interrupt 位置で graph が停止する」。
+ *
+ * Verifies that `wiki-compose-research` halts at `human_review_research` with
+ * a structurally-correct payload after the loop exits (single iteration when
+ * evaluation crosses the threshold).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+} = vi.hoisted(() => ({
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+}));
+
+// The real `human_review_research` calls `interrupt()` which we want to
+// exercise; everything else is mocked to keep the test deterministic.
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  RESEARCH_GRAPH_ID,
+  registerResearchLoopGraph,
+} from "../../../../agents/subgraphs/research/index.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+import { MemorySaver } from "@langchain/langgraph";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "thread-interrupt",
+    sessionId: "thread-interrupt",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: RESEARCH_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+describe("researchLoopSubgraph — interrupt at human_review_research", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerResearchLoopGraph();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("halts at human_review_research after a single-iteration loop", async () => {
+    planQueries.mockImplementation(async () => ({
+      queries: [{ id: "q1", query: "init", channels: ["web"] }],
+      maxIterations: 3,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async () => ({
+      pendingSources: [{ id: "src:abc", kind: "web", title: "A", url: "https://a/" }],
+    }));
+    wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+    evaluateSufficiency.mockImplementation(async (state, _c) => ({
+      lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+      iteration: state.iteration + 1,
+      phase: "research:evaluated",
+    }));
+    compileBatch.mockImplementation(async (state, _c) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }));
+
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: fakeContext(),
+        // Interrupt resume requires a checkpointer; use MemorySaver for tests.
+        // interrupt の再開には checkpointer が必要。テストでは MemorySaver を使う。
+        checkpointer: new MemorySaver(),
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+
+    expect(result.status).toBe("interrupted");
+    // GraphRunner extracts the node name from the interrupt error if available;
+    // structural check is enough since LangGraph version churn can change the
+    // exact attribute name.
+    // interruptedAt はバージョン差で空になり得るので、最低限 status を担保する。
+    if (result.interruptedAt !== undefined) {
+      expect(result.interruptedAt).toMatch(/human_review_research|interrupt/i);
+    }
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.loop.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.loop.test.ts
new file mode 100644
index 00000000..b2e1600c
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.loop.test.ts
@@ -0,0 +1,241 @@
+/**
+ * issue #949 受け入れ条件 #1:
+ * 「subgraph が maxIterations まで自律ループする Vitest がある」。
+ *
+ * Tests that the compiled `wiki-compose-research` graph loops exactly
+ * `maxIterations` times when `evaluate_sufficiency` keeps returning a low
+ * score, and exits at `compile_batch` with `exitReason: "max_iterations"`.
+ *
+ * Strategy: mock the nodes barrel (`./nodes/index.js`) so each LLM-bound node
+ * is a deterministic `vi.fn()`. We invoke the real `registerResearchLoopGraph`
+ * factory through `GraphRunner` so edges + reducers + checkpointer integration
+ * are exercised end-to-end, but the network-touching bits are replaced.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// `vi.mock` is hoisted to the top of the module, so the captured `vi.fn()`
+// instances must be hoisted alongside it via `vi.hoisted()`. Otherwise the
+// factory closes over `undefined` variables.
+// vi.mock のホイストに合わせて、参照する vi.fn() も vi.hoisted で揚げる。
+const {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+  humanReviewResearch,
+} = vi.hoisted(() => ({
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+  humanReviewResearch: vi.fn(),
+}));
+
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  // shouldRefine is the *real* pure function so the conditional edge actually
+  // routes by the values we feed in via the mocked evaluate_sufficiency.
+  // shouldRefine だけは本物を呼び、条件分岐の挙動を実際に確かめる。
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+    humanReviewResearch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import {
+  __resetRegistryForTests,
+  registerGraph,
+} from "../../../../agents/registry/graphRegistry.js";
+import {
+  RESEARCH_GRAPH_ID,
+  registerResearchLoopGraph,
+} from "../../../../agents/subgraphs/research/index.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+
+function fakeContext(graphId: string): GraphContext {
+  return {
+    threadId: "thread-loop",
+    sessionId: "thread-loop",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+describe("researchLoopSubgraph — autonomous loop", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerResearchLoopGraph();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+    humanReviewResearch.mockReset();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("loops exactly `maxIterations` times when evaluation never reaches threshold", async () => {
+    const maxIterations = 3;
+
+    planQueries.mockImplementation(async (_state, _config) => ({
+      queries: [{ id: "q-init", query: "init", channels: ["web"] }],
+      maxIterations,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async (_state, _config) => ({
+      pendingSources: [{ id: "src:a", kind: "web", title: "A", url: "https://a/" }],
+    }));
+    wikiSearch.mockImplementation(async (_state, _config) => ({ pendingSources: [] }));
+    fetchArticles.mockImplementation(async (_state, _config) => ({ pendingSources: [] }));
+
+    // evaluate_sufficiency post-increments iteration; we mirror that here.
+    let evaluatedTimes = 0;
+    evaluateSufficiency.mockImplementation(async (state, _config) => {
+      evaluatedTimes += 1;
+      return {
+        lastEvaluation: { score: 0.1, rationale: "weak", missingAspects: ["x"] },
+        iteration: state.iteration + 1,
+        phase: "research:evaluated",
+      };
+    });
+
+    refineQueries.mockImplementation(async (state, _config) => ({
+      queries: [
+        { id: `q-${state.iteration}`, query: `refined-${state.iteration}`, channels: ["web"] },
+      ],
+      phase: "research:refine",
+    }));
+
+    compileBatch.mockImplementation(async (state, _config) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "max_iterations",
+      phase: "research:compile",
+    }));
+
+    // human_review_research interrupts; we shortcut here by returning a normal
+    // update so the loop test focuses on iteration accounting, not HITL.
+    // HITL は別テストで検証する。ループ計測のため interrupt を回避。
+    humanReviewResearch.mockImplementation(async (_state, _config) => ({
+      approvedResearch: [],
+      rejectedResearch: [],
+      phase: "completed",
+    }));
+
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: fakeContext(RESEARCH_GRAPH_ID),
+        checkpointer: false,
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+
+    expect(result.status).toBe("completed");
+    // evaluate runs N times where N === maxIterations (initial run + each refine).
+    // evaluate は maxIterations 回走る（初回 + refine ごと）。
+    expect(evaluatedTimes).toBe(maxIterations);
+    expect(refineQueries).toHaveBeenCalledTimes(maxIterations - 1);
+    expect(compileBatch).toHaveBeenCalledTimes(1);
+    expect(humanReviewResearch).toHaveBeenCalledTimes(1);
+  });
+
+  it("exits early when evaluation crosses the 0.75 threshold", async () => {
+    planQueries.mockImplementation(async (_s, _c) => ({
+      queries: [{ id: "q1", query: "init", channels: ["web"] }],
+      maxIterations: 5,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+    evaluateSufficiency.mockImplementation(async (state, _c) => ({
+      lastEvaluation: { score: 0.9, rationale: "great", missingAspects: [] },
+      iteration: state.iteration + 1,
+      phase: "research:evaluated",
+    }));
+    refineQueries.mockImplementation(async () => ({ queries: [], phase: "research:refine" }));
+    compileBatch.mockImplementation(async (state, _c) => ({
+      batches: [
+        {
+          id: "batch-early",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }));
+    humanReviewResearch.mockImplementation(async () => ({
+      approvedResearch: [],
+      rejectedResearch: [],
+      phase: "completed",
+    }));
+
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: fakeContext(RESEARCH_GRAPH_ID),
+        checkpointer: false,
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+
+    expect(result.status).toBe("completed");
+    // Single iteration: evaluate once, refine never, compile once.
+    expect(evaluateSufficiency).toHaveBeenCalledTimes(1);
+    expect(refineQueries).not.toHaveBeenCalled();
+    expect(compileBatch).toHaveBeenCalledTimes(1);
+  });
+});
+
+// Lint guard so a stray top-level registerGraph call cannot pollute the registry.
+void registerGraph;
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.modelGuard.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.modelGuard.test.ts
new file mode 100644
index 00000000..cc73f668
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.modelGuard.test.ts
@@ -0,0 +1,169 @@
+/**
+ * issue #949 受け入れ条件 #6:
+ * 「全 LLM 呼び出しが `ZediChatModel` 経由」。
+ *
+ * Mocks the `createZediChatModel` factory and asserts that every LLM-bound
+ * node (`plan_queries`, `evaluate_sufficiency`, `refine_queries`) calls the
+ * factory at least once during a real (non-mocked-node) loop. The tools are
+ * still mocked at the barrel level so we don't make network calls.
+ *
+ * Note: this does NOT test for the *absence* of other LLM clients — that's a
+ * code-review concern. The factory call count check catches the most common
+ * regression (a node reaching for a provider client directly).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { createZediChatModel } = vi.hoisted(() => ({ createZediChatModel: vi.fn() }));
+
+vi.mock("../../../../agents/core/llm/modelFactory.js", async () => {
+  const actual = await vi.importActual<
+    typeof import("../../../../agents/core/llm/modelFactory.js")
+  >("../../../../agents/core/llm/modelFactory.js");
+  return {
+    ...actual,
+    createZediChatModel: (...args: unknown[]) =>
+      createZediChatModel(...(args as Parameters)),
+  };
+});
+
+// Mock the tools so they don't try to hit anything real. We test their bodies
+// individually elsewhere.
+// tools は別テストで検証するので、本テストでは empty 応答で済ます。
+vi.mock("../../../../agents/core/tools/webSearch.js", async () => {
+  const { tool } = await import("@langchain/core/tools");
+  const { z } = await import("zod");
+  return {
+    WEB_SEARCH_TOOL_NAME: "web_search",
+    webSearchInputSchema: z.object({ query: z.string(), limit: z.number().optional() }),
+    webSearchTool: tool(async () => JSON.stringify({ ok: true, results: [] }), {
+      name: "web_search",
+      description: "stub",
+      schema: z.object({ query: z.string(), limit: z.number().optional() }),
+    }),
+  };
+});
+vi.mock("../../../../agents/core/tools/wikiSearch.js", async () => {
+  const { tool } = await import("@langchain/core/tools");
+  const { z } = await import("zod");
+  return {
+    WIKI_SEARCH_TOOL_NAME: "wiki_search",
+    wikiSearchInputSchema: z.object({ query: z.string(), limit: z.number().optional() }),
+    wikiSearchTool: tool(async () => JSON.stringify({ ok: true, results: [] }), {
+      name: "wiki_search",
+      description: "stub",
+      schema: z.object({ query: z.string(), limit: z.number().optional() }),
+    }),
+  };
+});
+vi.mock("../../../../agents/core/tools/fetchArticle.js", async () => {
+  const { tool } = await import("@langchain/core/tools");
+  const { z } = await import("zod");
+  return {
+    FETCH_ARTICLE_TOOL_NAME: "fetch_article",
+    fetchArticleInputSchema: z.object({ url: z.string(), previewLength: z.number().optional() }),
+    fetchArticleTool: tool(async () => JSON.stringify({ ok: false, url: "", error: "stub" }), {
+      name: "fetch_article",
+      description: "stub",
+      schema: z.object({ url: z.string(), previewLength: z.number().optional() }),
+    }),
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  RESEARCH_GRAPH_ID,
+  registerResearchLoopGraph,
+} from "../../../../agents/subgraphs/research/index.js";
+import { MemorySaver } from "@langchain/langgraph";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "thread-guard",
+    sessionId: "thread-guard",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: RESEARCH_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+/** Build a fake ZediChatModel-shaped object with a `withStructuredOutput` chain. */
+function fakeModel(structuredReturn: () => Promise) {
+  const runnable = {
+    invoke: vi.fn(async (_messages: unknown) => structuredReturn()),
+  };
+  return {
+    withStructuredOutput: vi.fn((_schema: unknown, _opts?: unknown) => runnable),
+  };
+}
+
+describe("researchLoopSubgraph — all LLM calls go through ZediChatModel", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerResearchLoopGraph();
+    createZediChatModel.mockReset();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("invokes createZediChatModel for plan, evaluate, and refine", async () => {
+    // Plan returns 2 queries (1 web, 1 wiki) so web_search + wiki_search both fire.
+    // Evaluate returns score 0.1 forcing one refine, then evaluate returns 0.9.
+    let evaluateCall = 0;
+    createZediChatModel.mockImplementation(async (input: { feature: string }) => {
+      if (input.feature.endsWith(":plan")) {
+        return fakeModel(async () => ({
+          queries: [
+            { query: "q-web", channels: ["web"] },
+            { query: "q-wiki", channels: ["wiki"] },
+          ],
+        }));
+      }
+      if (input.feature.endsWith(":evaluate")) {
+        evaluateCall += 1;
+        const score = evaluateCall >= 2 ? 0.9 : 0.1;
+        return fakeModel(async () => ({
+          score,
+          rationale: "auto",
+          missingAspects: score < 0.75 ? ["x"] : [],
+        }));
+      }
+      if (input.feature.endsWith(":refine")) {
+        return fakeModel(async () => ({
+          queries: [{ query: "q-refined", channels: ["web"] }],
+        }));
+      }
+      throw new Error(`unexpected feature ${input.feature}`);
+    });
+
+    const runner = new GraphRunner();
+    await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: fakeContext(),
+        checkpointer: new MemorySaver(),
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+
+    const features = createZediChatModel.mock.calls.map(
+      (call) => (call[0] as { feature: string }).feature,
+    );
+    expect(features).toContain("wiki_compose:research:plan");
+    expect(features).toContain("wiki_compose:research:evaluate");
+    expect(features).toContain("wiki_compose:research:refine");
+    // No raw aiProviders / OpenAI / Anthropic clients should be imported by the
+    // research-loop nodes; only `createZediChatModel` is mocked. If a node ever
+    // imports a provider SDK directly, this test will still pass — code review
+    // is the second line of defence.
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/researchGraph.resume.test.ts b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.resume.test.ts
new file mode 100644
index 00000000..756245d4
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/researchGraph.resume.test.ts
@@ -0,0 +1,238 @@
+/**
+ * issue #949 受け入れ条件 #4:
+ * 「resume で approvedResearch が state に反映される」。
+ *
+ * Drives the graph to interrupt at `human_review_research`, then resumes with
+ * a structured `{ approvedSourceIds, rejectedSourceIds }` payload and asserts
+ * that the final state's `approvedResearch` and `rejectedResearch` arrays
+ * reflect the choice.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+} = vi.hoisted(() => ({
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+}));
+
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  RESEARCH_GRAPH_ID,
+  registerResearchLoopGraph,
+} from "../../../../agents/subgraphs/research/index.js";
+import { getRegisteredGraph } from "../../../../agents/registry/graphRegistry.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+import { Command, MemorySaver } from "@langchain/langgraph";
+
+function fakeContext(): GraphContext {
+  return {
+    threadId: "thread-resume",
+    sessionId: "thread-resume",
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: RESEARCH_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:research",
+    userEmail: null,
+  };
+}
+
+describe("researchLoopSubgraph — resume projects approvedResearch", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerResearchLoopGraph();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("populates approvedResearch / rejectedResearch from the resume payload", async () => {
+    const pending = [
+      { id: "src:a", kind: "web" as const, title: "A", url: "https://a/" },
+      { id: "src:b", kind: "web" as const, title: "B", url: "https://b/" },
+      { id: "wiki:p", kind: "wiki" as const, title: "P", pageId: "p", noteId: "n" },
+    ];
+
+    planQueries.mockImplementation(async () => ({
+      queries: [{ id: "q1", query: "init", channels: ["web"] }],
+      maxIterations: 3,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async () => ({ pendingSources: pending.slice(0, 2) }));
+    wikiSearch.mockImplementation(async () => ({ pendingSources: pending.slice(2) }));
+    fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+    evaluateSufficiency.mockImplementation(async (state, _c) => ({
+      lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+      iteration: state.iteration + 1,
+      phase: "research:evaluated",
+    }));
+    compileBatch.mockImplementation(async (state, _c) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }));
+
+    // GraphRunner.resume goes through `invoke` internally; we drive the same
+    // sequence here so we can read the final compiled state after resume.
+    // GraphRunner.resume を経由しつつ、最終 state を読むために自前で
+    // compiled graph を組み立てる（registry + checkpointer 経由は同じ）。
+    const registered = getRegisteredGraph(RESEARCH_GRAPH_ID);
+    if (!registered) throw new Error("graph not registered");
+    const checkpointer = new MemorySaver();
+    const compiled = registered.factory({ checkpointer }) as {
+      invoke: (input: unknown, options: unknown) => Promise;
+      getState?: (options: unknown) => Promise;
+    };
+
+    const config = {
+      configurable: {
+        thread_id: "thread-resume",
+        zediGraphContext: fakeContext(),
+      },
+      recursionLimit: 60,
+    };
+
+    // 1st invoke runs to the interrupt. LangGraph 1.x surfaces interrupts as
+    // a `__interrupt__: Interrupt[]` array on the returned state instead of
+    // throwing, so we check for that shape.
+    // LangGraph 1.x では interrupt は throw されず、結果 state の
+    // `__interrupt__` 配列に乗る。throw 経路ではなく field を見る。
+    const firstResult = (await compiled.invoke(
+      { messages: [{ role: "user", content: "brief" }] },
+      config,
+    )) as { __interrupt__?: Array<{ value: unknown }> };
+    expect(Array.isArray(firstResult.__interrupt__)).toBe(true);
+    expect(firstResult.__interrupt__?.length).toBeGreaterThan(0);
+
+    // 2nd invoke resumes with the approval payload.
+    const finalState = (await compiled.invoke(
+      new Command({
+        resume: {
+          approvedSourceIds: ["src:a", "wiki:p"],
+          rejectedSourceIds: ["src:b"],
+        },
+      }),
+      config,
+    )) as {
+      approvedResearch: Array<{ id: string }>;
+      rejectedResearch: Array<{ id: string }>;
+      phase: string;
+    };
+
+    expect(finalState.approvedResearch.map((s) => s.id).sort()).toEqual(["src:a", "wiki:p"].sort());
+    expect(finalState.rejectedResearch.map((s) => s.id)).toEqual(["src:b"]);
+    expect(finalState.phase).toBe("completed");
+  });
+
+  it("rejects an ill-formed resume payload", async () => {
+    planQueries.mockImplementation(async () => ({
+      queries: [{ id: "q1", query: "init", channels: ["web"] }],
+      maxIterations: 3,
+      iteration: 0,
+      lastEvaluation: null,
+      exitReason: null,
+      phase: "research:plan",
+    }));
+    webSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+    fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+    evaluateSufficiency.mockImplementation(async (state, _c) => ({
+      lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+      iteration: state.iteration + 1,
+      phase: "research:evaluated",
+    }));
+    compileBatch.mockImplementation(async (state, _c) => ({
+      batches: [
+        {
+          id: "batch-bad",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }));
+
+    const runner = new GraphRunner();
+    const checkpointer = new MemorySaver();
+    const ctx = fakeContext();
+    // Use a fresh thread id so interrupt/resume state doesn't collide with
+    // the previous test in the same MemorySaver instance.
+    // テスト間で thread_id を分けて checkpointer 衝突を避ける。
+    const isolated = { ...ctx, threadId: "thread-resume-bad", sessionId: "thread-resume-bad" };
+
+    // First call: should interrupt.
+    const first = await runner.invoke(
+      {
+        graphId: RESEARCH_GRAPH_ID,
+        context: isolated,
+        checkpointer,
+        recursionLimit: 60,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "brief" }] } },
+    );
+    expect(first.status).toBe("interrupted");
+
+    // Resume with a payload that fails `researchResumeSchema` validation.
+    const bad = await runner.resume(
+      { graphId: RESEARCH_GRAPH_ID, context: isolated, checkpointer, recursionLimit: 60 },
+      { approvedSourceIds: [42] as unknown as string[] },
+    );
+    expect(bad.status).toBe("failed");
+    expect(bad.error).toBeDefined();
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/tools/fetchArticle.test.ts b/server/api/src/__tests__/agents/subgraphs/research/tools/fetchArticle.test.ts
new file mode 100644
index 00000000..4b979059
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/tools/fetchArticle.test.ts
@@ -0,0 +1,95 @@
+/**
+ * `fetchArticleTool` unit tests. Covers:
+ * - SSRF rejection: `isClipUrlAllowedAfterDns` returns false → `{ ok:false, error:"url_blocked" }`.
+ * - Happy path: `extractArticleFromUrl` returns an article → success envelope.
+ * - Extractor throw → error envelope (no rethrow).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { isClipUrlAllowedAfterDns, extractArticleFromUrl } = vi.hoisted(() => ({
+  isClipUrlAllowedAfterDns: vi.fn(),
+  extractArticleFromUrl: vi.fn(),
+}));
+
+vi.mock("../../../../../lib/clipUrlPolicy.js", () => ({
+  isClipUrlAllowedAfterDns: (...args: unknown[]) =>
+    isClipUrlAllowedAfterDns(
+      ...(args as Parameters<
+        typeof import("../../../../../lib/clipUrlPolicy.js").isClipUrlAllowedAfterDns
+      >),
+    ),
+}));
+
+vi.mock("../../../../../lib/articleExtractor.js", async () => {
+  const actual = await vi.importActual(
+    "../../../../../lib/articleExtractor.js",
+  );
+  return {
+    ...actual,
+    extractArticleFromUrl: (...args: unknown[]) =>
+      extractArticleFromUrl(
+        ...(args as Parameters<
+          typeof import("../../../../../lib/articleExtractor.js").extractArticleFromUrl
+        >),
+      ),
+  };
+});
+
+import { fetchArticleTool } from "../../../../../agents/core/tools/fetchArticle.js";
+
+beforeEach(() => {
+  isClipUrlAllowedAfterDns.mockReset();
+  extractArticleFromUrl.mockReset();
+});
+afterEach(() => {
+  isClipUrlAllowedAfterDns.mockReset();
+  extractArticleFromUrl.mockReset();
+});
+
+describe("fetchArticleTool", () => {
+  it("rejects blocked URLs without calling the extractor", async () => {
+    isClipUrlAllowedAfterDns.mockResolvedValueOnce(false);
+    const raw = await fetchArticleTool.invoke({ url: "http://internal/" });
+    expect(extractArticleFromUrl).not.toHaveBeenCalled();
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("url_blocked");
+  });
+
+  it("returns an article envelope on success", async () => {
+    isClipUrlAllowedAfterDns.mockResolvedValueOnce(true);
+    extractArticleFromUrl.mockResolvedValueOnce({
+      finalUrl: "https://final/",
+      title: "T",
+      thumbnailUrl: null,
+      tiptapJson: { type: "doc" },
+      contentText: "body",
+      contentHash: "abc",
+    });
+    const raw = await fetchArticleTool.invoke({ url: "https://x/", previewLength: 1000 });
+    const parsed = JSON.parse(raw as string) as {
+      ok: boolean;
+      finalUrl: string;
+      title: string;
+      excerpt: string;
+      contentHash: string;
+    };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.finalUrl).toBe("https://final/");
+    expect(parsed.title).toBe("T");
+    expect(parsed.excerpt).toBe("body");
+    expect(parsed.contentHash).toBe("abc");
+    expect(extractArticleFromUrl).toHaveBeenCalledWith(
+      expect.objectContaining({ url: "https://x/", previewLength: 1000 }),
+    );
+  });
+
+  it("wraps extractor errors in a non-throwing envelope", async () => {
+    isClipUrlAllowedAfterDns.mockResolvedValueOnce(true);
+    extractArticleFromUrl.mockRejectedValueOnce(new Error("network fail"));
+    const raw = await fetchArticleTool.invoke({ url: "https://x/" });
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("network fail");
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/tools/webSearch.test.ts b/server/api/src/__tests__/agents/subgraphs/research/tools/webSearch.test.ts
new file mode 100644
index 00000000..f2cb7c85
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/tools/webSearch.test.ts
@@ -0,0 +1,84 @@
+/**
+ * `webSearchTool` unit tests. Covers:
+ * - Missing graph context → JSON envelope `{ ok:false, error:"missing_graph_context" }`.
+ * - No OpenAI/Google model configured → `{ ok:true, results:[], note:"web_search_unavailable" }`
+ *   (the Anthropic-fallback path documented in the tool's JSDoc).
+ *
+ * We don't fully exercise the LLM path here — `researchGraph.modelGuard.test.ts`
+ * already verifies that the tool routes through `createZediChatModel`, and the
+ * structured-output shape is covered indirectly by the loop test. Adding a
+ * full network mock would be brittle for marginal value.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { resolveWebSearchModelId } = vi.hoisted(() => ({ resolveWebSearchModelId: vi.fn() }));
+
+vi.mock("../../../../../agents/core/tools/resolveWebSearchModel.js", () => ({
+  resolveWebSearchModelId: (...args: unknown[]) =>
+    resolveWebSearchModelId(
+      ...(args as Parameters<
+        typeof import("../../../../../agents/core/tools/resolveWebSearchModel.js").resolveWebSearchModelId
+      >),
+    ),
+}));
+
+import { webSearchTool } from "../../../../../agents/core/tools/webSearch.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../../../../../agents/core/types/graphContext.js";
+import type { GraphContext } from "../../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../../types/index.js";
+
+function ctxConfig(): { configurable: Record } {
+  return {
+    configurable: {
+      [GRAPH_CONTEXT_CONFIG_KEY]: {
+        threadId: "t",
+        sessionId: "t",
+        userId: "u-1",
+        pageId: "p-1",
+        graphId: "wiki-compose-research",
+        backend: "zedi_managed",
+        tier: "free",
+        db: {} as Database,
+        feature: "wiki_compose:research",
+        userEmail: null,
+      } satisfies GraphContext,
+    },
+  };
+}
+
+beforeEach(() => {
+  resolveWebSearchModelId.mockReset();
+});
+afterEach(() => {
+  resolveWebSearchModelId.mockReset();
+});
+
+describe("webSearchTool", () => {
+  it("reports missing_graph_context when called without configurable", async () => {
+    const raw = await webSearchTool.invoke({ query: "ripgrep" });
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("missing_graph_context");
+  });
+
+  it("returns the documented fallback when no managed web-search model is configured", async () => {
+    resolveWebSearchModelId.mockResolvedValueOnce(null);
+    const raw = await webSearchTool.invoke({ query: "ripgrep" }, ctxConfig());
+    const parsed = JSON.parse(raw as string) as {
+      ok: boolean;
+      results: unknown[];
+      note?: string;
+    };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.results).toEqual([]);
+    expect(parsed.note).toBe("web_search_unavailable");
+  });
+
+  it("returns an error envelope when model resolution itself throws", async () => {
+    resolveWebSearchModelId.mockRejectedValueOnce(new Error("db unreachable"));
+    const raw = await webSearchTool.invoke({ query: "x" }, ctxConfig());
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toMatch(/web_search_model_resolution_failed:db unreachable/);
+  });
+});
diff --git a/server/api/src/__tests__/agents/subgraphs/research/tools/wikiSearch.test.ts b/server/api/src/__tests__/agents/subgraphs/research/tools/wikiSearch.test.ts
new file mode 100644
index 00000000..d696231f
--- /dev/null
+++ b/server/api/src/__tests__/agents/subgraphs/research/tools/wikiSearch.test.ts
@@ -0,0 +1,110 @@
+/**
+ * `wikiSearchTool` unit tests. Covers:
+ * - Missing graph context → JSON envelope `{ ok:false, error:"missing_graph_context" }`.
+ * - Happy path: forwards `userId` / `userEmail` to `searchUserWikiPages` and
+ *   maps hits to the on-wire `Source` envelope with stable `wiki:` ids.
+ * - Service error → JSON envelope `{ ok:false, error }`.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { searchUserWikiPages } = vi.hoisted(() => ({ searchUserWikiPages: vi.fn() }));
+vi.mock("../../../../../services/wikiSearchService.js", () => ({
+  searchUserWikiPages: (...args: unknown[]) =>
+    searchUserWikiPages(
+      ...(args as Parameters<
+        typeof import("../../../../../services/wikiSearchService.js").searchUserWikiPages
+      >),
+    ),
+}));
+
+import { wikiSearchTool } from "../../../../../agents/core/tools/wikiSearch.js";
+import { GRAPH_CONTEXT_CONFIG_KEY } from "../../../../../agents/core/types/graphContext.js";
+import type { GraphContext } from "../../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../../types/index.js";
+
+function ctxConfig(overrides: Partial = {}): {
+  configurable: Record;
+} {
+  return {
+    configurable: {
+      [GRAPH_CONTEXT_CONFIG_KEY]: {
+        threadId: "t",
+        sessionId: "t",
+        userId: "u-1",
+        pageId: "p-1",
+        graphId: "wiki-compose-research",
+        backend: "zedi_managed",
+        tier: "free",
+        db: {} as Database,
+        feature: "wiki_compose:research",
+        userEmail: "alice@example.com",
+        ...overrides,
+      } satisfies GraphContext,
+    },
+  };
+}
+
+beforeEach(() => {
+  searchUserWikiPages.mockReset();
+});
+afterEach(() => {
+  searchUserWikiPages.mockReset();
+});
+
+describe("wikiSearchTool", () => {
+  it("reports missing_graph_context when called without configurable", async () => {
+    const raw = await wikiSearchTool.invoke({ query: "ripgrep" });
+    expect(typeof raw).toBe("string");
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("missing_graph_context");
+  });
+
+  it("forwards userId / userEmail and maps service hits to wiki sources", async () => {
+    searchUserWikiPages.mockResolvedValueOnce([
+      {
+        pageId: "page-1",
+        noteId: "note-1",
+        title: "Alpha",
+        contentPreview: "preview",
+        updatedAt: "2026-01-01T00:00:00.000Z",
+      },
+    ]);
+    const raw = await wikiSearchTool.invoke(
+      { query: "alpha", limit: 7 },
+      ctxConfig({ userId: "u-7", userEmail: "u7@x.com" }),
+    );
+    expect(searchUserWikiPages).toHaveBeenCalledWith(
+      expect.anything(),
+      "u-7",
+      "u7@x.com",
+      "alpha",
+      "shared",
+      7,
+    );
+    const parsed = JSON.parse(raw as string) as {
+      ok: boolean;
+      results: Array<{ id: string; kind: string; pageId: string; noteId: string; title: string }>;
+    };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.results).toEqual([
+      {
+        id: "wiki:page-1",
+        kind: "wiki",
+        title: "Alpha",
+        pageId: "page-1",
+        noteId: "note-1",
+        snippet: "preview",
+      },
+    ]);
+  });
+
+  it("returns an error envelope when the service throws", async () => {
+    searchUserWikiPages.mockRejectedValueOnce(new Error("db down"));
+    const raw = await wikiSearchTool.invoke({ query: "x" }, ctxConfig());
+    const parsed = JSON.parse(raw as string) as { ok: boolean; error?: string; results: unknown[] };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error).toBe("db down");
+    expect(parsed.results).toEqual([]);
+  });
+});
diff --git a/server/api/src/__tests__/services/wikiSearchService.test.ts b/server/api/src/__tests__/services/wikiSearchService.test.ts
new file mode 100644
index 00000000..bf8315e9
--- /dev/null
+++ b/server/api/src/__tests__/services/wikiSearchService.test.ts
@@ -0,0 +1,115 @@
+/**
+ * `searchUserWikiPages` unit tests using the proxy mock DB. We assert:
+ * - Empty query returns `[]` without touching the DB.
+ * - `scope="own"` calls `getDefaultNoteOrNull` and short-circuits when null.
+ * - `scope="shared"` runs the user-scoped SQL and maps rows to `WikiSearchHit`.
+ * - `limit` is clamped to 1..100.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const { getDefaultNoteOrNull } = vi.hoisted(() => ({ getDefaultNoteOrNull: vi.fn() }));
+
+vi.mock("../../services/defaultNoteService.js", () => ({
+  getDefaultNoteOrNull: (...args: unknown[]) =>
+    getDefaultNoteOrNull(
+      ...(args as Parameters<
+        typeof import("../../services/defaultNoteService.js").getDefaultNoteOrNull
+      >),
+    ),
+}));
+
+import { searchUserWikiPages } from "../../services/wikiSearchService.js";
+import { createMockDb } from "../createMockDb.js";
+import type { Database } from "../../types/index.js";
+
+beforeEach(() => {
+  getDefaultNoteOrNull.mockReset();
+});
+afterEach(() => {
+  getDefaultNoteOrNull.mockReset();
+});
+
+describe("searchUserWikiPages", () => {
+  it("returns [] for empty query without DB access", async () => {
+    const { db, chains } = createMockDb([]);
+    const out = await searchUserWikiPages(
+      db as unknown as Database,
+      "u-1",
+      null,
+      "  ",
+      "shared",
+      10,
+    );
+    expect(out).toEqual([]);
+    expect(chains.length).toBe(0);
+    expect(getDefaultNoteOrNull).not.toHaveBeenCalled();
+  });
+
+  it("scope=own short-circuits when there is no default note", async () => {
+    getDefaultNoteOrNull.mockResolvedValueOnce(null);
+    const { db, chains } = createMockDb([]);
+    const out = await searchUserWikiPages(db as unknown as Database, "u-1", null, "x", "own", 10);
+    expect(out).toEqual([]);
+    expect(chains.length).toBe(0);
+  });
+
+  it("scope=shared executes the SQL and maps rows", async () => {
+    const rows = {
+      rows: [
+        {
+          id: "page-1",
+          note_id: "note-1",
+          title: "T1",
+          content_preview: "P1",
+          updated_at: "2026-01-01T00:00:00Z",
+        },
+        {
+          id: "page-2",
+          note_id: "note-2",
+          title: null,
+          content_preview: null,
+          updated_at: "2026-01-02T00:00:00Z",
+        },
+      ],
+    };
+    const { db, chains } = createMockDb([rows]);
+    const out = await searchUserWikiPages(
+      db as unknown as Database,
+      "u-1",
+      "alice@example.com",
+      "alpha",
+      "shared",
+      5,
+    );
+    expect(chains.length).toBe(1);
+    expect(chains[0]?.startMethod).toBe("execute");
+    expect(out).toEqual([
+      {
+        pageId: "page-1",
+        noteId: "note-1",
+        title: "T1",
+        contentPreview: "P1",
+        updatedAt: "2026-01-01T00:00:00Z",
+      },
+      {
+        pageId: "page-2",
+        noteId: "note-2",
+        title: null,
+        contentPreview: null,
+        updatedAt: "2026-01-02T00:00:00Z",
+      },
+    ]);
+  });
+
+  it("clamps limit to 1..100", async () => {
+    getDefaultNoteOrNull.mockResolvedValueOnce({ id: "n-default" });
+    const { db } = createMockDb([{ rows: [] }]);
+    await searchUserWikiPages(db as unknown as Database, "u-1", null, "x", "own", 9999);
+    // No throw is the assertion here; the proxy mock doesn't expose the SQL
+    // template's bound `limit` directly, but `safeLimit` is computed before the
+    // query is issued so this exercises the clamping branch.
+    // clamp は execute 前に評価される。proxy mock では bind 値を読み出せないため、
+    // 例外が出ないことだけ確認する。
+    expect(true).toBe(true);
+  });
+});
diff --git a/server/api/src/agents/core/llm/modelFactory.ts b/server/api/src/agents/core/llm/modelFactory.ts
index 7aa88c8e..b6ff738a 100644
--- a/server/api/src/agents/core/llm/modelFactory.ts
+++ b/server/api/src/agents/core/llm/modelFactory.ts
@@ -18,7 +18,7 @@ import {
   SUPPORTED_BACKENDS_P0,
   type ExecutionBackend,
 } from "../types/executionBackend.js";
-import { ZediChatModel } from "./zediChatModel.js";
+import { ZediChatModel, type ExtraProviderOptions } from "./zediChatModel.js";
 
 /**
  * `createZediChatModel` の入力。
@@ -48,6 +48,8 @@ export interface CreateZediChatModelInput {
   apiKey?: string;
   temperature?: number;
   maxTokens?: number;
+  /** プロバイダ固有 pass-through。`useWebSearch` 等。Optional provider knobs. */
+  extraProviderOptions?: ExtraProviderOptions;
 }
 
 /**
@@ -115,6 +117,7 @@ export async function createZediChatModel(input: CreateZediChatModelInput): Prom
     apiMode,
     temperature: input.temperature,
     maxTokens: input.maxTokens,
+    extraProviderOptions: input.extraProviderOptions,
   });
 }
 
diff --git a/server/api/src/agents/core/llm/zediChatModel.ts b/server/api/src/agents/core/llm/zediChatModel.ts
index 4defd29b..d7ea74e0 100644
--- a/server/api/src/agents/core/llm/zediChatModel.ts
+++ b/server/api/src/agents/core/llm/zediChatModel.ts
@@ -41,7 +41,13 @@ import type { BaseMessage } from "@langchain/core/messages";
 import { AIMessage, AIMessageChunk } from "@langchain/core/messages";
 import { ChatGenerationChunk, type ChatResult } from "@langchain/core/outputs";
 import { callProvider, streamProvider } from "../../../services/aiProviders.js";
-import type { AIProviderType, ApiMode, Database, UserTier } from "../../../types/index.js";
+import type {
+  AIChatOptions,
+  AIProviderType,
+  ApiMode,
+  Database,
+  UserTier,
+} from "../../../types/index.js";
 import { recordZediUsage, toZediMessages } from "./usageCallback.js";
 
 /**
@@ -80,6 +86,16 @@ export interface StreamProviderFn {
  * @property apiMode           "system" / "user_key"。P0 では "system"。BYOK 時に切替。
  * @property callProvider      `callProvider` の差し替え（任意）。Optional override.
  * @property streamProvider    `streamProvider` の差し替え（任意）。Optional override.
+ * @property extraProviderOptions  `callProvider` / `streamProvider` に追加で渡す
+ *                                 オプション。`useWebSearch` / `useGoogleSearch` /
+ *                                 `webSearchOptions` などプロバイダ固有ノブを
+ *                                 LangGraph ノードから通すための薄い pass-through。
+ *                                 Per-provider pass-through options merged into
+ *                                 the `AIChatOptions` bag passed to
+ *                                 `callProvider` / `streamProvider`. Lets nodes
+ *                                 enable provider-side web search etc. without
+ *                                 widening the constructor surface for every
+ *                                 future knob.
  */
 export interface ZediChatModelParams extends BaseChatModelParams {
   provider: AIProviderType;
@@ -98,8 +114,24 @@ export interface ZediChatModelParams extends BaseChatModelParams {
   /** モデル呼び出しオプション。temperature / maxTokens 等。Provider options. */
   temperature?: number;
   maxTokens?: number;
+  extraProviderOptions?: ExtraProviderOptions;
 }
 
+/**
+ * `callProvider` / `streamProvider` に追加で渡すプロバイダ固有オプションの
+ * サブセット。`AIChatOptions` から `feature`/`temperature`/`maxTokens`/`stream`
+ * を除いた pass-through ノブ群（web 検索フラグ等）。
+ *
+ * Subset of {@link AIChatOptions} containing provider-specific knobs that
+ * subgraphs may need to flip per call (e.g. `useWebSearch` for the research
+ * loop's `web_search` tool). Kept narrow so the model class doesn't accept
+ * arbitrary call options that would bypass usage accounting.
+ */
+export type ExtraProviderOptions = Pick<
+  AIChatOptions,
+  "useWebSearch" | "useGoogleSearch" | "webSearchOptions"
+>;
+
 /**
  * Concrete `BaseChatModel` implementation routing through Zedi providers.
  * Zedi の providers 経由で呼び出す `BaseChatModel` 実装。
@@ -125,6 +157,7 @@ export class ZediChatModel extends BaseChatModel {
   private readonly streamProviderFn: StreamProviderFn;
   private readonly temperature?: number;
   private readonly maxTokens?: number;
+  private readonly extraProviderOptions?: ExtraProviderOptions;
 
   constructor(fields: ZediChatModelParams) {
     super(fields);
@@ -143,6 +176,7 @@ export class ZediChatModel extends BaseChatModel {
     this.streamProviderFn = fields.streamProvider ?? streamProvider;
     this.temperature = fields.temperature;
     this.maxTokens = fields.maxTokens;
+    this.extraProviderOptions = fields.extraProviderOptions;
   }
 
   /**
@@ -172,6 +206,7 @@ export class ZediChatModel extends BaseChatModel {
         temperature: this.temperature,
         maxTokens: this.maxTokens,
         feature: this.feature,
+        ...this.extraProviderOptions,
       },
     );
 
@@ -241,6 +276,7 @@ export class ZediChatModel extends BaseChatModel {
       temperature: this.temperature,
       maxTokens: this.maxTokens,
       feature: this.feature,
+      ...this.extraProviderOptions,
     });
 
     let accumulated = "";
diff --git a/server/api/src/agents/core/tools/fetchArticle.ts b/server/api/src/agents/core/tools/fetchArticle.ts
index a828d6cc..b7c316b3 100644
--- a/server/api/src/agents/core/tools/fetchArticle.ts
+++ b/server/api/src/agents/core/tools/fetchArticle.ts
@@ -1,20 +1,27 @@
 /**
- * `fetch_article` tool stub.
+ * `fetch_article` tool — fetches and Readability-extracts a URL into a
+ * preview-sized excerpt.
  *
- * URL を渡すと Readability ベースで本文を抽出する tool（既存 `extractArticleFromUrl`
- * を将来流用する想定）。P0 ではスキーマだけ確定。
+ * LangGraph tool wrapping {@link extractArticleFromUrl}. SSRF-guarded with the
+ * same `isClipUrlAllowedAfterDns` check that `/api/clip` and `clipServerFetch`
+ * use. Returns a JSON-stringified envelope `{ ok, ...fields | error }`. Errors
+ * (block, fetch timeout, parse failure) never throw — the caller node maps
+ * `ok:false` to a removed source so a single bad URL does not abort the
+ * research iteration.
  *
- * Article extractor by URL. Real implementation reuses `extractArticleFromUrl`
- * in `lib/articleExtractor.ts`; P0 only fixes the contract.
+ * `extractArticleFromUrl` を tool 化した版。SSRF 防御は `clipUrlPolicy` の
+ * `isClipUrlAllowedAfterDns` を流用する。失敗時は `{ ok:false, error }` を
+ * JSON 文字列で返す（throw しない）ことで、調査ループの 1 イテレーションが
+ * 1 件の URL 不調で停止しないようにする。
  */
 import { tool } from "@langchain/core/tools";
 import { z } from "zod";
+import { extractArticleFromUrl, ClipFetchBlockedError } from "../../../lib/articleExtractor.js";
+import { isClipUrlAllowedAfterDns } from "../../../lib/clipUrlPolicy.js";
 
 /** Tool name. */
 export const FETCH_ARTICLE_TOOL_NAME = "fetch_article" as const;
 
-const STUB_RESPONSE_PREFIX = "FETCH_ARTICLE_NOT_IMPLEMENTED";
-
 /**
  * Input schema. URL は http/https のみ。previewLength は 500〜8000。
  * Input schema; URL must be http/https, `previewLength` clamps to 500..8000.
@@ -35,17 +42,57 @@ export const fetchArticleInputSchema = z.object({
 });
 
 /**
- * P0 stub. Real implementation routes through `extractArticleFromUrl` with the
- * same SSRF guards (`isAllowedUrlForArticleFetch`) already used by `/api/clip`
- * and `/api/ingest/plan`.
+ * 成功時 JSON 包絡型。失敗時は `{ ok:false, error }` で返す。
  *
- * P0 スタブ。実装は `extractArticleFromUrl` を経由し、`/api/clip` 等と同じ
- * SSRF 防御 (`isAllowedUrlForArticleFetch`) を通す。
+ * Success envelope; failure shape is `{ ok:false, error }`. The caller node
+ * always `JSON.parse`s and branches on `ok`.
  */
+interface FetchArticleSuccess {
+  ok: true;
+  url: string;
+  finalUrl: string;
+  title: string;
+  excerpt: string;
+  contentHash: string;
+  thumbnailUrl: string | null;
+}
+
+interface FetchArticleFailure {
+  ok: false;
+  url: string;
+  error: string;
+}
+
 export const fetchArticleTool = tool(
   async (input) => {
-    const summary = `${STUB_RESPONSE_PREFIX} url=${JSON.stringify(input.url)}`;
-    return summary;
+    const url = input.url;
+    const previewLength = input.previewLength ?? 4000;
+    if (!(await isClipUrlAllowedAfterDns(url))) {
+      const fail: FetchArticleFailure = { ok: false, url, error: "url_blocked" };
+      return JSON.stringify(fail);
+    }
+    try {
+      const article = await extractArticleFromUrl({ url, previewLength });
+      const ok: FetchArticleSuccess = {
+        ok: true,
+        url,
+        finalUrl: article.finalUrl,
+        title: article.title,
+        excerpt: article.contentText,
+        contentHash: article.contentHash,
+        thumbnailUrl: article.thumbnailUrl,
+      };
+      return JSON.stringify(ok);
+    } catch (err) {
+      const error =
+        err instanceof ClipFetchBlockedError
+          ? "url_blocked"
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      const fail: FetchArticleFailure = { ok: false, url, error };
+      return JSON.stringify(fail);
+    }
   },
   {
     name: FETCH_ARTICLE_TOOL_NAME,
diff --git a/server/api/src/agents/core/tools/resolveWebSearchModel.ts b/server/api/src/agents/core/tools/resolveWebSearchModel.ts
new file mode 100644
index 00000000..896f922c
--- /dev/null
+++ b/server/api/src/agents/core/tools/resolveWebSearchModel.ts
@@ -0,0 +1,103 @@
+/**
+ * `resolveWebSearchModel` — pick the LLM model the `web_search` tool should run.
+ *
+ * `webSearchTool` は provider 内蔵の web 検索 (`useWebSearch` for OpenAI,
+ * `useGoogleSearch` for Google) を呼ぶため、Anthropic-only な選択では成立しない。
+ * 本ヘルパは次の優先順で model を選ぶ:
+ *
+ * 1. `process.env.WIKI_COMPOSE_WEB_SEARCH_MODEL_ID` (explicit override; `ai_models.id`)
+ *    — 必ず active かつ tier 通過することを DB 側で確認する（coderabbit review #956:
+ *    不正な override で `createZediChatModel` が失敗してエラー envelope になる
+ *    のを防ぐ）。
+ * 2. `ai_models` の active な OpenAI モデルで最安 (`input_cost_units` ASC, `output_cost_units` ASC)
+ * 3. `ai_models` の active な Google モデルで最安
+ * 4. 何も無ければ `null` を返す（ツール側は empty result + note を返す）。
+ *
+ * Returns the `ai_models.id` so `createZediChatModel({ modelId })` can validate
+ * tier access and resolve the API key uniformly. Centralising the choice in one
+ * helper keeps the tool body small and makes the Anthropic-fallback policy
+ * easy to revisit.
+ *
+ * The `tier` argument filters out `tierRequired === "pro"` rows for free users,
+ * so a free-tier caller never sees `web_search_unavailable_for_tier` surface as
+ * an error — they cleanly fall back to "no results" + note (coderabbit #956).
+ */
+import { and, asc, eq, inArray } from "drizzle-orm";
+import { aiModels } from "../../../schema/index.js";
+import type { Database, UserTier } from "../../../types/index.js";
+
+const ENV_OVERRIDE = "WIKI_COMPOSE_WEB_SEARCH_MODEL_ID";
+
+/**
+ * Tier-aware predicate: `free` users only see `tierRequired = "free"` models;
+ * `pro` users see both.
+ *
+ * tier ガード。`free` ユーザは `tierRequired = "free"` のモデルだけ見える。
+ */
+function tierFilter(tier: UserTier) {
+  if (tier === "pro") return undefined;
+  return eq(aiModels.tierRequired, "free");
+}
+
+/**
+ * Resolve the model id used by `webSearchTool`. Returns `null` when no
+ * suitable model exists (e.g. Anthropic-only seed, or the env override is
+ * not active / not accessible to the caller's tier). Pure read-only DB query.
+ */
+export async function resolveWebSearchModelId(
+  db: Database,
+  tier: UserTier,
+): Promise {
+  const override = process.env[ENV_OVERRIDE]?.trim();
+  if (override) {
+    // Validate the override before returning: it must be active and
+    // accessible to the caller's tier, otherwise `createZediChatModel`
+    // would throw and surface as an `ok:false` envelope instead of the
+    // intended graceful unavailable path.
+    // override も active + tier 通過性を DB で検証する。
+    const tierClause = tierFilter(tier);
+    const [row] = await db
+      .select({ id: aiModels.id })
+      .from(aiModels)
+      .where(
+        and(
+          eq(aiModels.id, override),
+          eq(aiModels.isActive, true),
+          ...(tierClause ? [tierClause] : []),
+        ),
+      )
+      .limit(1);
+    if (row) return row.id;
+    // Override resolved but unusable → fall through to the standard lookup
+    // rather than returning the broken id.
+    // override が使えない場合は通常検索にフォールバックする。
+  }
+
+  const tierClause = tierFilter(tier);
+  const rows = await db
+    .select({
+      id: aiModels.id,
+      provider: aiModels.provider,
+      inputCostUnits: aiModels.inputCostUnits,
+      outputCostUnits: aiModels.outputCostUnits,
+    })
+    .from(aiModels)
+    .where(
+      and(
+        eq(aiModels.isActive, true),
+        inArray(aiModels.provider, ["openai", "google"]),
+        ...(tierClause ? [tierClause] : []),
+      ),
+    )
+    .orderBy(asc(aiModels.inputCostUnits), asc(aiModels.outputCostUnits));
+
+  // Prefer OpenAI when costs tie, since `useWebSearch` (chat completions
+  // `web_search_options`) is well-tested in `aiProviders.ts`; Google's
+  // `googleSearch` tool is also supported but requires the `tools` payload.
+  // 同コストなら OpenAI を優先（`useWebSearch` 経路が安定）。
+  const openai = rows.find((r) => r.provider === "openai");
+  if (openai) return openai.id;
+  const google = rows.find((r) => r.provider === "google");
+  if (google) return google.id;
+  return null;
+}
diff --git a/server/api/src/agents/core/tools/webSearch.ts b/server/api/src/agents/core/tools/webSearch.ts
index dbfa4bdd..81858a0e 100644
--- a/server/api/src/agents/core/tools/webSearch.ts
+++ b/server/api/src/agents/core/tools/webSearch.ts
@@ -1,22 +1,39 @@
 /**
- * `web_search` tool stub for the Wiki Compose research subgraph (#949).
+ * `web_search` tool — runs a provider-internal web search and returns a
+ * structured `{title,url,snippet}` list.
  *
- * Web 検索 tool のスタブ。本実装は #949 (P1 調査 subgraph) で行うが、P0 では
- * LangGraph tool として bind 可能な形と zod スキーマ・名前空間だけ確定させ、
- * 呼び出し時は `WEB_SEARCH_NOT_IMPLEMENTED` を返す。
+ * Provider routing (issue #949):
+ * - `process.env.WIKI_COMPOSE_WEB_SEARCH_MODEL_ID` (`ai_models.id` override) >
+ * - cheapest active OpenAI model (`useWebSearch`) >
+ * - cheapest active Google model (`useGoogleSearch`).
  *
- * Stub web search tool. P0 only fixes the name + zod schema so subgraphs can
- * `bindTools([webSearchTool])` without breakage; behaviour ships in #949.
+ * If the session was created with `backend === "zedi_managed"` but no suitable
+ * model exists (Anthropic-only seed, or no API keys configured), the tool
+ * returns `{ ok:true, results:[], note:"web_search_unavailable" }` so the
+ * `evaluate_sufficiency` node can carry on instead of throwing. The fallback
+ * is intentional: `evaluate_sufficiency` already handles empty results, and
+ * raising would tank the whole loop on a misconfigured env.
+ *
+ * LLM 呼び出しは `createZediChatModel` 経由で行うため、usage 記録は P0 で
+ * 確立した課金経路にそのまま乗る。`extraProviderOptions` で `useWebSearch` /
+ * `useGoogleSearch` を pass-through する。
+ *
+ * The LLM call goes through `createZediChatModel`, so usage attribution flows
+ * through the existing `recordUsage` path established in P0 (#948).
  */
 import { tool } from "@langchain/core/tools";
 import { z } from "zod";
+import { eq } from "drizzle-orm";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { GRAPH_CONTEXT_CONFIG_KEY, type GraphContext } from "../types/graphContext.js";
+import { createZediChatModel } from "../llm/modelFactory.js";
+import { resolveWebSearchModelId } from "./resolveWebSearchModel.js";
+import type { ExtraProviderOptions } from "../llm/zediChatModel.js";
+import { aiModels } from "../../../schema/index.js";
 
 /** Tool name shared across subgraphs. 全 subgraph 共通の tool 名。 */
 export const WEB_SEARCH_TOOL_NAME = "web_search" as const;
 
-/** Stub response surfaced when the tool is called before #949 lands. */
-const STUB_RESPONSE_PREFIX = "WEB_SEARCH_NOT_IMPLEMENTED";
-
 /**
  * Input schema (zod). `query` は必須、`limit` は 1〜10、`recencyDays` は省略可。
  * Input schema; `query` required, `limit` 1..10, `recencyDays` optional.
@@ -38,18 +55,134 @@ export const webSearchInputSchema = z.object({
     .describe("Restrict to results within N days. N 日以内の結果に限定。"),
 });
 
-/**
- * P0 stub. Bound by subgraphs via `model.bindTools([webSearchTool])`. The body
- * intentionally returns a sentinel string so research subgraphs that depend on
- * it surface a visible failure mode rather than silent empty results.
- *
- * P0 スタブ。呼び出されたら sentinel を返し、依存する subgraph が静かに空結果を
- * 受け取るのを防ぐ。
- */
+const webSearchResultSchema = z.object({
+  results: z
+    .array(
+      z.object({
+        title: z.string().min(1),
+        url: z.string().url(),
+        snippet: z.string().optional(),
+      }),
+    )
+    .max(10),
+});
+
+const SYSTEM_PROMPT =
+  "You are a web search assistant. Use the provider's native web search to find " +
+  "fresh, relevant pages for the user's query. Reply with JSON only, matching the " +
+  "provided schema. Do not invent URLs; only include sources you actually retrieved.";
+
+function buildUserPrompt(query: string, limit: number, recencyDays: number | undefined): string {
+  const constraints: string[] = [];
+  if (recencyDays !== undefined) constraints.push(`Restrict to the last ${recencyDays} days.`);
+  constraints.push(`Return at most ${limit} results.`);
+  return [`Query: ${query}`, ...constraints].join("\n");
+}
+
+/** Hit shape emitted on the wire (serialised as JSON). */
+interface WebSearchToolHit {
+  /**
+   * Stable Source id: `src:`. Shared with `kind:"fetched"` so the
+   * reducer (`mergeSourcesById`) upgrades the row in place when Readability
+   * succeeds on the same URL.
+   * web/fetched は同じ id 体系 (`src:`) を使うことで reducer が in-place
+   * 昇格できる（codex review #956 P2 / gemini #4）。
+   */
+  id: string;
+  kind: "web";
+  title: string;
+  url: string;
+  snippet?: string;
+}
+
+interface WebSearchSuccess {
+  ok: true;
+  results: WebSearchToolHit[];
+  /** Optional explanatory note (e.g. fallback path). */
+  note?: string;
+}
+
+interface WebSearchFailure {
+  ok: false;
+  error: string;
+  results: [];
+}
+
 export const webSearchTool = tool(
-  async (input) => {
-    const summary = `${STUB_RESPONSE_PREFIX} query=${JSON.stringify(input.query)}`;
-    return summary;
+  async (input, config?: LangGraphRunnableConfig) => {
+    const ctx = readGraphContext(config);
+    if (!ctx) {
+      return JSON.stringify({
+        ok: false,
+        error: "missing_graph_context",
+        results: [],
+      } satisfies WebSearchFailure);
+    }
+    const limit = input.limit ?? 5;
+    const recencyDays = input.recencyDays;
+
+    let modelId: string | null;
+    try {
+      modelId = await resolveWebSearchModelId(ctx.db, ctx.tier);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return JSON.stringify({
+        ok: false,
+        error: `web_search_model_resolution_failed:${message}`,
+        results: [],
+      } satisfies WebSearchFailure);
+    }
+
+    if (!modelId) {
+      // No OpenAI/Google model configured. Return empty results so the loop
+      // can carry on; `evaluate_sufficiency` is tolerant of empty channels.
+      // OpenAI / Google モデルが見つからない場合は空結果 + note を返す。
+      return JSON.stringify({
+        ok: true,
+        results: [],
+        note: "web_search_unavailable",
+      } satisfies WebSearchSuccess);
+    }
+
+    try {
+      const provider = await detectProviderForModelId(ctx, modelId);
+      const extraProviderOptions = providerOptions(provider);
+      const model = await createZediChatModel({
+        modelId,
+        userId: ctx.userId,
+        tier: ctx.tier,
+        db: ctx.db,
+        feature: `${ctx.feature}:web_search`,
+        backend: "zedi_managed",
+        temperature: 0.2,
+        maxTokens: 1024,
+        extraProviderOptions,
+      });
+      const structured = model.withStructuredOutput(webSearchResultSchema, {
+        name: "web_search_results",
+      });
+      const parsed = await structured.invoke([
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: buildUserPrompt(input.query, limit, recencyDays) },
+      ]);
+      const results: WebSearchToolHit[] = await Promise.all(
+        parsed.results.slice(0, limit).map(async (r) => ({
+          id: `src:${await sha256Hex(r.url)}`,
+          kind: "web",
+          title: r.title,
+          url: r.url,
+          snippet: r.snippet,
+        })),
+      );
+      return JSON.stringify({ ok: true, results } satisfies WebSearchSuccess);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return JSON.stringify({
+        ok: false,
+        error: message,
+        results: [],
+      } satisfies WebSearchFailure);
+    }
   },
   {
     name: WEB_SEARCH_TOOL_NAME,
@@ -59,3 +192,60 @@ export const webSearchTool = tool(
     schema: webSearchInputSchema,
   },
 );
+
+function readGraphContext(config: LangGraphRunnableConfig | undefined): GraphContext | null {
+  const configurable = config?.configurable as Record | undefined;
+  const candidate = configurable?.[GRAPH_CONTEXT_CONFIG_KEY];
+  if (!candidate || typeof candidate !== "object") return null;
+  return candidate as GraphContext;
+}
+
+/**
+ * Look up the provider for a given `ai_models.id`. We could reuse
+ * `validateModelAccess` but that throws for tier-blocked models and we don't
+ * want a tier check here (the call is at the `web_search` feature, billed to
+ * the user regardless of which model is picked).
+ *
+ * Returns "openai" / "google" / "anthropic". Throws if the model is missing.
+ */
+async function detectProviderForModelId(
+  ctx: GraphContext,
+  modelId: string,
+): Promise<"openai" | "anthropic" | "google"> {
+  const [row] = await ctx.db
+    .select({ provider: aiModels.provider })
+    .from(aiModels)
+    .where(eq(aiModels.id, modelId))
+    .limit(1);
+  if (!row) throw new Error(`Model not found: ${modelId}`);
+  if (row.provider === "openai" || row.provider === "anthropic" || row.provider === "google") {
+    return row.provider;
+  }
+  throw new Error(`Unknown provider for model ${modelId}: ${row.provider}`);
+}
+
+function providerOptions(provider: "openai" | "anthropic" | "google"): ExtraProviderOptions {
+  if (provider === "openai") {
+    return { useWebSearch: true, webSearchOptions: { search_context_size: "medium" } };
+  }
+  if (provider === "google") {
+    return { useGoogleSearch: true };
+  }
+  // Anthropic is not selected by `resolveWebSearchModelId`; this is defensive
+  // for the env-override branch. The structured prompt still works, just
+  // without provider-side search.
+  return {};
+}
+
+/**
+ * `sha256` hex digest of a string. Used to mint stable `Source.id` for web
+ * search hits so a URL appearing in iteration N upgrades to `kind:"fetched"`
+ * in iteration N+1 in place.
+ */
+async function sha256Hex(input: string): Promise {
+  const enc = new TextEncoder().encode(input);
+  const buf = await crypto.subtle.digest("SHA-256", enc);
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
diff --git a/server/api/src/agents/core/tools/wikiSearch.ts b/server/api/src/agents/core/tools/wikiSearch.ts
index decb146d..be4e12fe 100644
--- a/server/api/src/agents/core/tools/wikiSearch.ts
+++ b/server/api/src/agents/core/tools/wikiSearch.ts
@@ -1,20 +1,26 @@
 /**
- * `wiki_search` tool stub.
+ * `wiki_search` tool — searches the executing user's own wiki pages by keyword.
  *
- * ユーザー所有 Wiki 内のページ検索 tool。P0 ではスキーマと名前のみ固定し、
- * 中身は #949 (P1 調査 subgraph) で `/api/search` 相当のクエリに置き換える。
+ * LangGraph tool wrapping {@link searchUserWikiPages}. Reads `db` / `userId` /
+ * `userEmail` from `config.configurable[GRAPH_CONTEXT_CONFIG_KEY]` so the call
+ * is implicitly scoped to the caller — never trust `query` for authorisation,
+ * trust the runtime context. Returns a JSON string array of `Source`-shaped
+ * rows (`kind:"wiki"`); the calling node parses it back.
  *
- * Searches the executing user's wiki. P0 ships only the schema and name so
- * subgraphs can wire it up; the real implementation lands in #949.
+ * `routes/search.ts` の `scope=shared` 相当ロジック (`wikiSearchService`) を
+ * tool 経由で再利用する。ユーザー所有 + 受諾済みメンバー + ドメインルールを
+ * 横断する Wiki 検索を、`GraphContext` から取得した `userId` / `userEmail` で
+ * 安全に絞り込む。本ファイルは #949 で stub を本実装に差し替えた版。
  */
 import { tool } from "@langchain/core/tools";
 import { z } from "zod";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { GRAPH_CONTEXT_CONFIG_KEY, type GraphContext } from "../types/graphContext.js";
+import { searchUserWikiPages } from "../../../services/wikiSearchService.js";
 
 /** Tool name. */
 export const WIKI_SEARCH_TOOL_NAME = "wiki_search" as const;
 
-const STUB_RESPONSE_PREFIX = "WIKI_SEARCH_NOT_IMPLEMENTED";
-
 /**
  * Input schema. `query` は必須、`limit` は 1〜20。
  * Input schema.
@@ -30,18 +36,57 @@ export const wikiSearchInputSchema = z.object({
     .describe("Max results (default 10). 最大件数 (既定 10)。"),
 });
 
+/** Hit shape emitted on the wire (serialised as JSON). */
+interface WikiSearchToolHit {
+  /** Stable Source id: `wiki:`. */
+  id: string;
+  kind: "wiki";
+  title: string;
+  pageId: string;
+  noteId: string;
+  snippet?: string;
+}
+
 /**
- * P0 stub. Authorisation will be enforced by the future implementation: it must
- * filter by the executing user's owner_id pulled from `GraphContext.userId`,
- * not by any tool argument.
+ * 実装本体。`config.configurable` から graph context を引き、wikiSearchService
+ * を呼び出す。tool runtime に context が乗っていない場合（典型的にはユニット
+ * テストでの誤呼び出し）は `{ ok:false, error:"missing_graph_context" }` を
+ * 返して呼び出し側がそのまま JSON.parse できる形を維持する。
  *
- * P0 スタブ。実実装は `GraphContext.userId` から owner_id を取り出して絞り込み
- * する。tool 引数から userId を取らないこと（権限境界）。
+ * Read the `GraphContext` from the runtime config and invoke the service.
+ * Returns a JSON-string wrapped envelope so caller nodes can `JSON.parse`
+ * unconditionally — including the error branch, so a missing context does
+ * not blow up the entire iteration.
  */
 export const wikiSearchTool = tool(
-  async (input) => {
-    const summary = `${STUB_RESPONSE_PREFIX} query=${JSON.stringify(input.query)}`;
-    return summary;
+  async (input, config?: LangGraphRunnableConfig) => {
+    const ctx = readGraphContext(config);
+    if (!ctx) {
+      return JSON.stringify({ ok: false, error: "missing_graph_context", results: [] });
+    }
+    const limit = input.limit ?? 10;
+    try {
+      const hits = await searchUserWikiPages(
+        ctx.db,
+        ctx.userId,
+        ctx.userEmail,
+        input.query,
+        "shared",
+        limit,
+      );
+      const results: WikiSearchToolHit[] = hits.map((h) => ({
+        id: `wiki:${h.pageId}`,
+        kind: "wiki",
+        title: h.title ?? "(untitled)",
+        pageId: h.pageId,
+        noteId: h.noteId,
+        snippet: h.contentPreview ?? undefined,
+      }));
+      return JSON.stringify({ ok: true, results });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return JSON.stringify({ ok: false, error: message, results: [] });
+    }
   },
   {
     name: WIKI_SEARCH_TOOL_NAME,
@@ -51,3 +96,10 @@ export const wikiSearchTool = tool(
     schema: wikiSearchInputSchema,
   },
 );
+
+function readGraphContext(config: LangGraphRunnableConfig | undefined): GraphContext | null {
+  const configurable = config?.configurable as Record | undefined;
+  const candidate = configurable?.[GRAPH_CONTEXT_CONFIG_KEY];
+  if (!candidate || typeof candidate !== "object") return null;
+  return candidate as GraphContext;
+}
diff --git a/server/api/src/agents/core/types/graphContext.ts b/server/api/src/agents/core/types/graphContext.ts
index 30774ffe..a17572bd 100644
--- a/server/api/src/agents/core/types/graphContext.ts
+++ b/server/api/src/agents/core/types/graphContext.ts
@@ -27,6 +27,10 @@ import type { ExecutionBackend } from "./executionBackend.js";
  * @property tier      ユーザー tier（usage 上限判定で使う）。User tier for budget checks.
  * @property db        Drizzle DB ハンドル。Drizzle DB handle.
  * @property feature   `recordUsage` の feature ラベル。`recordUsage` feature label.
+ * @property userEmail 実行ユーザーのメール（domain ベース共有スコープ判定で使う）。
+ *                     Executing user's email; used by `wikiSearchService` to
+ *                     apply the `note_domain_access` predicate without an
+ *                     extra DB roundtrip per tool call.
  */
 export interface GraphContext {
   threadId: string;
@@ -38,6 +42,7 @@ export interface GraphContext {
   tier: UserTier;
   db: Database;
   feature: string;
+  userEmail: string | null;
 }
 
 /**
diff --git a/server/api/src/agents/core/types/index.ts b/server/api/src/agents/core/types/index.ts
index 6d41765f..f0bd67d3 100644
--- a/server/api/src/agents/core/types/index.ts
+++ b/server/api/src/agents/core/types/index.ts
@@ -23,5 +23,8 @@ export {
   type SseInterruptEvent,
   type SseDoneEvent,
   type SseErrorEvent,
+  type SseResearchIterationEvent,
+  type SseResearchEvaluationEvent,
+  type SseResearchBatchEvent,
   SSE_EVENT_NAMES,
 } from "./sseEvents.js";
diff --git a/server/api/src/agents/core/types/sseEvents.ts b/server/api/src/agents/core/types/sseEvents.ts
index 4ed33715..8af30f3d 100644
--- a/server/api/src/agents/core/types/sseEvents.ts
+++ b/server/api/src/agents/core/types/sseEvents.ts
@@ -107,6 +107,66 @@ export interface SseErrorEvent {
   retryable?: boolean;
 }
 
+/**
+ * 調査ループ subgraph (#949) の iteration 通知。`plan_queries` / `refine_queries`
+ * 終了時に 1 件発火し、UI が「N 回目を計画中…」と「N 回目を refine 中…」を
+ * 出し分けられるよう `status` を持つ。
+ *
+ * Per-iteration heartbeat from the research loop subgraph. Emitted by
+ * `plan_queries` (`status:"planned"`) and `refine_queries` (`status:"refined"`).
+ */
+export interface SseResearchIterationEvent {
+  type: "research_iteration";
+  /** 0-based iteration index at dispatch time. */
+  iteration: number;
+  /** Phase that produced this iteration's query set. */
+  status: "planned" | "refined";
+  /** Number of queries planned for this iteration. */
+  queryCount: number;
+}
+
+/**
+ * 調査ループ subgraph (#949) の充足度評価通知。`evaluate_sufficiency` 終了時に
+ * 1 件発火。0..1 のスコアと欠落数を含むが、`rationale` も同梱して UI が
+ * tooltip 等で利用できるようにする。
+ *
+ * Sufficiency evaluation result. Emitted by `evaluate_sufficiency`; carries the
+ * 0..1 score, a short rationale, and the missing-aspect count.
+ */
+export interface SseResearchEvaluationEvent {
+  type: "research_evaluation";
+  /** Iteration index after post-increment in `evaluate_sufficiency`. */
+  iteration: number;
+  /** 0..1. ≥ 0.75 → loop exits next. */
+  score: number;
+  /** Short natural-language rationale. */
+  rationale: string;
+  /** Count of missing aspects (full list lives in state, not on the wire). */
+  missingAspectsCount: number;
+}
+
+/**
+ * 調査ループ subgraph (#949) のバッチ完成通知。`compile_batch` 終了時に 1 件
+ * 発火。バッチ本体は state に乗っているので wire 上は ID + サマリのみ。
+ *
+ * One-shot batch summary emitted by `compile_batch`. The full batch lives in
+ * state; this event only carries the id + counts so the frontend knows when to
+ * fetch / render.
+ */
+export interface SseResearchBatchEvent {
+  type: "research_batch";
+  /** Stable batch uuid. */
+  batchId: string;
+  /** Iteration that produced the batch. */
+  iteration: number;
+  /** Snapshot size at compile time. */
+  sourceCount: number;
+  /** Last evaluation score (null only if compile fired before any evaluate). */
+  score: number | null;
+  /** Reason the loop exited. */
+  exitReason: "score_threshold" | "max_iterations";
+}
+
 /**
  * Wire-level SSE union.
  */
@@ -119,7 +179,10 @@ export type SseEvent =
   | SseUsageEvent
   | SseInterruptEvent
   | SseDoneEvent
-  | SseErrorEvent;
+  | SseErrorEvent
+  | SseResearchIterationEvent
+  | SseResearchEvaluationEvent
+  | SseResearchBatchEvent;
 
 /**
  * SSE event 名（`event:` 行に流す名前）。`SseEvent["type"]` と同値だが、
@@ -138,4 +201,7 @@ export const SSE_EVENT_NAMES = {
   interrupt: "interrupt",
   done: "done",
   error: "error",
+  researchIteration: "research_iteration",
+  researchEvaluation: "research_evaluation",
+  researchBatch: "research_batch",
 } as const satisfies Record;
diff --git a/server/api/src/agents/index.ts b/server/api/src/agents/index.ts
index 93313f29..f5747a37 100644
--- a/server/api/src/agents/index.ts
+++ b/server/api/src/agents/index.ts
@@ -68,3 +68,21 @@ export {
   errorEvent,
   type LangGraphRuntimeEvent,
 } from "./runner/sseMapper.js";
+export {
+  RESEARCH_GRAPH_ID,
+  RESEARCH_GRAPH_VERSION,
+  registerResearchLoopGraph,
+  shouldRefine,
+  ResearchLoopState,
+  type ResearchLoopStateType,
+  type ResearchLoopStateUpdate,
+  type Source as ResearchSource,
+  type PlannedQuery,
+  type Evaluation,
+  type ResearchBatch,
+  type ExitReason,
+  type ResearchResumeInput,
+  researchResumeSchema,
+  type ResearchResumeParsed,
+  type HumanReviewInterruptPayload,
+} from "./subgraphs/research/index.js";
diff --git a/server/api/src/agents/runner/graphRunner.ts b/server/api/src/agents/runner/graphRunner.ts
index 7babb64a..54262a60 100644
--- a/server/api/src/agents/runner/graphRunner.ts
+++ b/server/api/src/agents/runner/graphRunner.ts
@@ -71,11 +71,21 @@ export class GraphRunner {
     const config = this.buildConfig(input);
     try {
       const result = await graph.invoke(this.unwrapPayload(payload), config);
+      // LangGraph ≥ 1.x: interrupts surface as a `__interrupt__` array on the
+      // returned state, NOT as a thrown error. Detect that shape and translate
+      // to `{ status: "interrupted" }`. Legacy throw-based GraphInterrupt is
+      // also handled below for safety (kept for forward-compat / version skew).
+      // LangGraph 1.x では interrupt は throw されず、結果 state の
+      // `__interrupt__` フィールドに乗る。ここで検出して status を訳す。
+      if (hasInterruptOnResult(result)) {
+        return { status: "interrupted", output: result };
+      }
       return { status: "completed", output: result };
     } catch (err) {
-      // Interrupts surface as throws in LangGraph; the route layer maps these
-      // back to a 200 with `status: "interrupted"` so we do the same here.
-      // LangGraph の interrupt は例外として伝搬する。`isGraphInterrupt` で判定。
+      // Interrupts surface as throws in some older LangGraph paths; keep the
+      // catch for safety so a version that re-introduces the throw doesn't
+      // regress to a failed run.
+      // 古い LangGraph パスでは throw する可能性があるので catch を残す。
       if (isInterruptError(err)) {
         return { status: "interrupted", interruptedAt: extractInterruptNode(err) };
       }
@@ -170,3 +180,18 @@ function extractInterruptNode(err: unknown): string | undefined {
   const node = (err as { node?: unknown }).node;
   return typeof node === "string" ? node : undefined;
 }
+
+/**
+ * LangGraph ≥ 1.x leaves a `__interrupt__: Interrupt[]` array on the final
+ * state when an `interrupt(value)` call is awaiting resume. This helper
+ * surfaces that for `GraphRunner.invoke` / `.resume` so they can return
+ * `{ status: "interrupted" }` without inspecting the LangChain payload type.
+ *
+ * LangGraph 1.x の `__interrupt__` フィールドを検出する。型は意図的に緩い
+ * （構造的）にしてバージョン差を吸収する。
+ */
+function hasInterruptOnResult(result: unknown): boolean {
+  if (!result || typeof result !== "object") return false;
+  const arr = (result as { __interrupt__?: unknown }).__interrupt__;
+  return Array.isArray(arr) && arr.length > 0;
+}
diff --git a/server/api/src/agents/runner/sseMapper.ts b/server/api/src/agents/runner/sseMapper.ts
index 77b07ed1..986db56f 100644
--- a/server/api/src/agents/runner/sseMapper.ts
+++ b/server/api/src/agents/runner/sseMapper.ts
@@ -10,7 +10,12 @@
  * route layer is responsible for actually writing to the SSE response; this
  * file only describes the shape transformation so unit tests can pin it.
  */
-import type { SseEvent } from "../core/types/sseEvents.js";
+import type {
+  SseEvent,
+  SseResearchBatchEvent,
+  SseResearchEvaluationEvent,
+  SseResearchIterationEvent,
+} from "../core/types/sseEvents.js";
 
 /**
  * 起動時 SSE。`event: started` で投げる。
@@ -96,6 +101,8 @@ export function mapLangGraphEvent(event: LangGraphRuntimeEvent): SseEvent[] {
       return mapToolEnd(event);
     case "on_chain_end":
       return mapChainEnd(event);
+    case "on_custom_event":
+      return mapCustomEvent(event);
     default:
       return [];
   }
@@ -149,14 +156,106 @@ function mapToolEnd(event: LangGraphRuntimeEvent): SseEvent[] {
 }
 
 function mapChainEnd(event: LangGraphRuntimeEvent): SseEvent[] {
-  // Only emit a status update when the chain end belongs to the top-level
-  // graph (no parent ids in metadata). Nested chain ends would generate noise.
-  // トップレベル graph の終了のみ status を吐く。ネストした chain は無視する。
+  // Only emit a status / interrupt update when the chain end belongs to the
+  // top-level graph. Nested chain ends would generate noise.
+  // トップレベル graph の終了のみ拾う。ネストした chain は無視する。
   const data = asRecord(event.data);
   if (!data) return [];
   const output = asRecord(data.output);
   if (!output) return [];
+  const events: SseEvent[] = [];
+
+  // LangGraph ≥ 1.x: interrupts surface as a `__interrupt__: Interrupt[]`
+  // array on the final state, not as a throw. Convert each entry to its own
+  // `interrupt` SSE event so the frontend sees the same wire shape it would
+  // get from the legacy throw path. Route layer reads `interrupt` events to
+  // flip the session status to "interrupted".
+  // LangGraph 1.x の `__interrupt__` 配列を SSE interrupt イベントに変換する。
+  const interrupts = (output as { __interrupt__?: unknown }).__interrupt__;
+  if (Array.isArray(interrupts) && interrupts.length > 0) {
+    for (const entry of interrupts) {
+      const value =
+        entry && typeof entry === "object" ? (entry as { value?: unknown }).value : undefined;
+      events.push({ type: "interrupt", payload: value });
+    }
+  }
+
   const phase = typeof output.phase === "string" ? output.phase : undefined;
-  if (!phase) return [];
-  return [{ type: "status", phase }];
+  if (phase) events.push({ type: "status", phase });
+  return events;
+}
+
+/**
+ * Map `on_custom_event` (LangGraph's hook for `dispatchCustomEvent` from
+ * `@langchain/core/callbacks/dispatch`) to typed Sse events. Used by the
+ * research loop subgraph (#949) to surface `research_iteration` /
+ * `research_evaluation` / `research_batch` without inventing a new transport.
+ *
+ * `dispatchCustomEvent(name, data, config)` で吐かれる runtime event を SSE に
+ * 変換する。`event.name` でイベント種別を分岐し、`event.data` は信頼せず構造
+ * 的に検証してから dispatch する（ペイロードが壊れていれば空配列を返して
+ * フロントを壊さない）。
+ */
+function mapCustomEvent(event: LangGraphRuntimeEvent): SseEvent[] {
+  const name = event.name;
+  if (!name) return [];
+  const data = asRecord(event.data);
+  if (!data) return [];
+  switch (name) {
+    case "research_iteration":
+      return mapResearchIteration(data);
+    case "research_evaluation":
+      return mapResearchEvaluation(data);
+    case "research_batch":
+      return mapResearchBatch(data);
+    default:
+      // Unknown custom event names are dropped silently; emitting them as `status`
+      // would risk leaking implementation detail to the wire.
+      // 未知 name は静かに捨てる。`status` 等に流すと内部詳細が漏れる。
+      return [];
+  }
+}
+
+function mapResearchIteration(data: Record): SseResearchIterationEvent[] {
+  const iteration = typeof data.iteration === "number" ? data.iteration : null;
+  const status = data.status === "planned" || data.status === "refined" ? data.status : null;
+  const queryCount = typeof data.queryCount === "number" ? data.queryCount : null;
+  if (iteration === null || status === null || queryCount === null) return [];
+  return [{ type: "research_iteration", iteration, status, queryCount }];
+}
+
+function mapResearchEvaluation(data: Record): SseResearchEvaluationEvent[] {
+  const iteration = typeof data.iteration === "number" ? data.iteration : null;
+  const score = typeof data.score === "number" ? data.score : null;
+  const rationale = typeof data.rationale === "string" ? data.rationale : null;
+  const missingAspectsCount =
+    typeof data.missingAspectsCount === "number" ? data.missingAspectsCount : null;
+  if (iteration === null || score === null || rationale === null || missingAspectsCount === null) {
+    return [];
+  }
+  return [{ type: "research_evaluation", iteration, score, rationale, missingAspectsCount }];
+}
+
+function mapResearchBatch(data: Record): SseResearchBatchEvent[] {
+  const batchId = typeof data.batchId === "string" ? data.batchId : null;
+  const iteration = typeof data.iteration === "number" ? data.iteration : null;
+  const sourceCount = typeof data.sourceCount === "number" ? data.sourceCount : null;
+  const score = data.score === null || typeof data.score === "number" ? data.score : null;
+  const exitReason =
+    data.exitReason === "score_threshold" || data.exitReason === "max_iterations"
+      ? data.exitReason
+      : null;
+  if (batchId === null || iteration === null || sourceCount === null || exitReason === null) {
+    return [];
+  }
+  return [
+    {
+      type: "research_batch",
+      batchId,
+      iteration,
+      sourceCount,
+      score,
+      exitReason,
+    },
+  ];
 }
diff --git a/server/api/src/agents/subgraphs/research/index.ts b/server/api/src/agents/subgraphs/research/index.ts
new file mode 100644
index 00000000..b624e5e8
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/index.ts
@@ -0,0 +1,28 @@
+/**
+ * Wiki Compose research-loop subgraph (#949) — public barrel.
+ *
+ * 調査ループ subgraph の外向け window。`app.ts` / `agents/index.ts` から
+ * このファイル経由で `RESEARCH_GRAPH_ID` と `registerResearchLoopGraph` を
+ * 引く。直接ノードを import したいテストは `./nodes/index.js` を見る。
+ */
+export {
+  RESEARCH_GRAPH_ID,
+  RESEARCH_GRAPH_VERSION,
+  registerResearchLoopGraph,
+  shouldRefine,
+} from "./researchGraph.js";
+export {
+  ResearchLoopState,
+  type ResearchLoopStateType,
+  type ResearchLoopStateUpdate,
+} from "./state.js";
+export type {
+  Source,
+  PlannedQuery,
+  Evaluation,
+  ResearchBatch,
+  ExitReason,
+  ResearchResumeInput,
+} from "./types.js";
+export { researchResumeSchema, type ResearchResumeParsed } from "./resumeSchema.js";
+export type { HumanReviewInterruptPayload } from "./nodes/humanReviewResearch.js";
diff --git a/server/api/src/agents/subgraphs/research/nodes/compileBatch.ts b/server/api/src/agents/subgraphs/research/nodes/compileBatch.ts
new file mode 100644
index 00000000..b9561dfc
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/compileBatch.ts
@@ -0,0 +1,59 @@
+/**
+ * `compile_batch` — pure projection node that produces a {@link ResearchBatch}
+ * from the current state and emits a `research_batch` SSE custom event.
+ *
+ * pure な projection ノード。`pendingSources` のスナップショットを 1 件の
+ * {@link ResearchBatch} に固めて `batches` に append し、`exitReason` を確定する。
+ * LLM 呼び出しは行わない。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { dispatchResearchBatch } from "./shared/dispatchSseCustom.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { ExitReason, ResearchBatch } from "../types.js";
+
+/**
+ * `compile_batch` node — pure projection that freezes the current state into a
+ * UI-facing {@link ResearchBatch}, appends it to `state.batches`, and dispatches
+ * the `research_batch` SSE custom event.
+ *
+ * `compile_batch` ノード本体。`pendingSources` のスナップショットを 1 件の
+ * {@link ResearchBatch} に固めて `batches` に append し、`exitReason` を確定する。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (carries `GraphContext` + callbacks).
+ * @returns Partial state update: `{ batches: [newBatch], exitReason, phase }`.
+ */
+export async function compileBatch(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const score = state.lastEvaluation?.score ?? null;
+  const exitReason: ExitReason =
+    score !== null && score >= 0.75 ? "score_threshold" : "max_iterations";
+  const batch: ResearchBatch = {
+    id: randomUUID(),
+    iteration: state.iteration,
+    queries: state.queries,
+    sources: state.pendingSources,
+    evaluation: state.lastEvaluation,
+    createdAt: new Date().toISOString(),
+  };
+
+  await dispatchResearchBatch(
+    {
+      batchId: batch.id,
+      iteration: batch.iteration,
+      sourceCount: batch.sources.length,
+      score,
+      exitReason,
+    },
+    config,
+  );
+
+  return {
+    batches: [batch],
+    exitReason,
+    phase: "research:compile",
+  };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/evaluateSufficiency.ts b/server/api/src/agents/subgraphs/research/nodes/evaluateSufficiency.ts
new file mode 100644
index 00000000..7de4dfd3
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/evaluateSufficiency.ts
@@ -0,0 +1,115 @@
+/**
+ * `evaluate_sufficiency` — scores the current `pendingSources` against the
+ * brief, post-increments `iteration`, and emits a `research_evaluation` SSE
+ * custom event.
+ *
+ * 現在の `pendingSources` が brief を満たしているかを LLM で評価し、
+ * `score` (0..1) と `missingAspects` を返す。post-increment した `iteration`
+ * を返すことで、後段の `shouldRefine` がループ終了条件
+ * (`score >= 0.75 || iteration >= maxIterations`) を正しく判定できる。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { getGraphContext } from "./shared/getGraphContext.js";
+import { dispatchResearchEvaluation } from "./shared/dispatchSseCustom.js";
+import { getOrchestratorModelId } from "./planQueries.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { Evaluation } from "../types.js";
+
+export const evaluationSchema = z.object({
+  score: z.number().min(0).max(1),
+  rationale: z.string().min(1).max(500),
+  missingAspects: z.array(z.string().min(1)).max(5),
+});
+
+const SYSTEM_PROMPT =
+  "You are evaluating whether the research sources collected so far are sufficient " +
+  "to write the requested wiki article. Score 0..1 (≥0.75 means 'good enough'), " +
+  "give a short rationale, and list up to 5 missing aspects. Output JSON only.";
+
+function buildUserPrompt(state: ResearchLoopStateType): string {
+  const brief = state.messages
+    .map((m) => {
+      const raw = (m as { content?: unknown }).content;
+      return typeof raw === "string" ? raw : "";
+    })
+    .filter((s) => s.length > 0)
+    .join("\n\n");
+  const sourceLines = state.pendingSources.map((s, i) => {
+    const tag = s.kind === "fetched" ? "FETCHED" : s.kind === "wiki" ? "WIKI" : "WEB";
+    const body = s.excerpt ?? s.snippet ?? "(no preview)";
+    return `[${i + 1}] ${tag} ${s.title}\n${body}`;
+  });
+  return [
+    "[Brief]",
+    brief || "(empty brief — assume general coverage)",
+    "",
+    `[Sources collected: ${state.pendingSources.length}]`,
+    ...sourceLines,
+    "",
+    `Iteration so far: ${state.iteration} / ${state.maxIterations}`,
+  ].join("\n");
+}
+
+/**
+ * `evaluate_sufficiency` node — scores the gathered sources against the brief,
+ * post-increments `iteration`, and dispatches the `research_evaluation` SSE
+ * custom event. The conditional edge {@link shouldRefine} reads
+ * `lastEvaluation.score` + `iteration` to decide refine vs compile.
+ *
+ * 充足度評価ノード本体。LLM で `{ score, rationale, missingAspects }` を
+ * 構造化出力で得て、`iteration` を 1 進めて返す。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (carries `GraphContext` + callbacks).
+ * @returns Partial state update: `{ lastEvaluation, iteration, phase }`.
+ */
+export async function evaluateSufficiency(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const ctx = getGraphContext(config);
+
+  const model = await createZediChatModel({
+    modelId: getOrchestratorModelId(),
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:evaluate`,
+    backend: ctx.backend,
+    temperature: 0.1,
+    // 1024 leaves enough room for a verbose `rationale` + `missingAspects`
+    // array without truncating mid-JSON (gemini review #956).
+    maxTokens: 1024,
+  });
+  const structured = model.withStructuredOutput(evaluationSchema, {
+    name: "research_evaluation",
+  });
+  const parsed = await structured.invoke([
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: buildUserPrompt(state) },
+  ]);
+  const evaluation: Evaluation = {
+    score: parsed.score,
+    rationale: parsed.rationale,
+    missingAspects: parsed.missingAspects,
+  };
+  const nextIteration = state.iteration + 1;
+
+  await dispatchResearchEvaluation(
+    {
+      iteration: nextIteration,
+      score: evaluation.score,
+      rationale: evaluation.rationale,
+      missingAspectsCount: evaluation.missingAspects.length,
+    },
+    config,
+  );
+
+  return {
+    lastEvaluation: evaluation,
+    iteration: nextIteration,
+    phase: "research:evaluated",
+  };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/fetchArticles.ts b/server/api/src/agents/subgraphs/research/nodes/fetchArticles.ts
new file mode 100644
index 00000000..d936a694
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/fetchArticles.ts
@@ -0,0 +1,109 @@
+/**
+ * `fetch_articles` node — Readability-extracts the top web URLs from
+ * `pendingSources` into excerpts and upgrades each source's `kind` from
+ * `web` to `fetched` IN PLACE via the id-keyed reducer.
+ *
+ * Web 検索結果のうち URL を持つ上位 N 件 (既定 5) を `fetchArticleTool` で取得。
+ * SSRF / fetch 失敗時は `{ ok:false }` を返すだけで throw しないため、1 件の
+ * 失敗で iteration が止まらない。
+ *
+ * In-place upgrade contract (codex review #956 / gemini #4):
+ * - web rows mint id = `src:` (in `webSearch.ts`).
+ * - fetched rows reuse that SAME id (carry the source row's `id` over) so the
+ *   reducer overwrites the web row with the fetched row in place. The
+ *   redirect-resolved URL goes to `finalUrl`; `url` stays equal to the
+ *   original so id derivation remains stable across iterations.
+ * - Failed fetches leave the web row untouched; a future iteration may retry.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { fetchArticleTool } from "../../../core/tools/fetchArticle.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { Source } from "../types.js";
+
+interface FetchArticleSuccess {
+  ok: true;
+  url: string;
+  finalUrl: string;
+  title: string;
+  excerpt: string;
+  contentHash: string;
+  thumbnailUrl: string | null;
+}
+
+interface FetchArticleFailure {
+  ok: false;
+  url: string;
+  error: string;
+}
+
+const PER_ITERATION_FETCH_LIMIT = 5;
+
+/**
+ * `fetch_articles` node — Readability-extracts up to {@link PER_ITERATION_FETCH_LIMIT}
+ * pending `web` rows in parallel and emits `kind:"fetched"` upgrades. The
+ * reducer ({@link mergeSourcesById}) overwrites each upgraded row in place
+ * because fetched sources carry the same `src:` id as the originating
+ * web row (codex review #956 P2 / gemini #4).
+ *
+ * fetch_articles ノード本体。pending な `web` 行を最大 N 件並列で取得し、
+ * `kind:"fetched"` に in-place 昇格させる。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (carries `GraphContext` + callbacks).
+ * @returns Partial state update: `{ pendingSources: upgradedRows[] }`.
+ */
+export async function fetchArticles(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  // Only fetch `web` rows. `fetched` rows share the same id (`src:`) so
+  // any web hit already promoted in a prior iteration has been overwritten by
+  // the reducer and is no longer present as `kind:"web"`.
+  // web 行のみ対象。同 URL の fetched 行は同じ id を持つため、過去 iteration で
+  // 昇格済みのものは reducer が上書きしており、ここでは現れない。
+  const candidates = state.pendingSources
+    .filter((s) => s.kind === "web" && typeof s.url === "string" && s.url.length > 0)
+    .slice(0, PER_ITERATION_FETCH_LIMIT);
+
+  if (candidates.length === 0) return { pendingSources: [] };
+
+  const settled = await Promise.allSettled(
+    candidates.map((s) =>
+      fetchArticleTool.invoke({ url: s.url as string, previewLength: 4000 }, config),
+    ),
+  );
+
+  const upgraded: Source[] = [];
+  const fetchedAt = new Date().toISOString();
+  for (let i = 0; i < settled.length; i++) {
+    const r = settled[i];
+    if (!r || r.status !== "fulfilled") continue;
+    const candidate = candidates[i];
+    if (!candidate) continue;
+    const raw = r.value;
+    if (typeof raw !== "string") continue;
+    let envelope: FetchArticleSuccess | FetchArticleFailure;
+    try {
+      envelope = JSON.parse(raw) as FetchArticleSuccess | FetchArticleFailure;
+    } catch {
+      continue;
+    }
+    if (!envelope.ok) continue;
+    // Carry the candidate's id over so the reducer upgrades the row in place.
+    // `url` stays equal to the original; the redirect-resolved URL is stored
+    // separately on `finalUrl` (codex review #956 P2).
+    // candidate.id を引き継いで reducer に in-place 昇格させる。url は元のまま、
+    // リダイレクト後は finalUrl に。
+    upgraded.push({
+      id: candidate.id,
+      kind: "fetched",
+      title: envelope.title,
+      url: candidate.url,
+      finalUrl: envelope.finalUrl,
+      excerpt: envelope.excerpt,
+      contentHash: envelope.contentHash,
+      fetchedAt,
+    });
+  }
+  return { pendingSources: upgraded };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/humanReviewResearch.ts b/server/api/src/agents/subgraphs/research/nodes/humanReviewResearch.ts
new file mode 100644
index 00000000..61205bc4
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/humanReviewResearch.ts
@@ -0,0 +1,79 @@
+/**
+ * `human_review_research` — HITL stop point. Calls `interrupt(...)` to halt
+ * the graph and surfaces the latest batch + pending sources to the client.
+ * On resume, validates the `{ approvedSourceIds, rejectedSourceIds, note }`
+ * payload and projects `approvedResearch` / `rejectedResearch` into state.
+ *
+ * HITL 中断ノード。`interrupt()` でグラフを停止し、UI には最新バッチと
+ * pendingSources を渡す。resume 時、`PATCH .../resume` 経由で送られてくる
+ * `{ approvedSourceIds, rejectedSourceIds?, note? }` を `researchResumeSchema`
+ * で検証し、`approvedResearch` / `rejectedResearch` を state に確定する。
+ * バリデーション失敗は throw され、`graphRunner` が `{ status:"failed" }` を
+ * 返して route 層が 4xx を返す。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { interrupt } from "@langchain/langgraph";
+import { researchResumeSchema } from "../resumeSchema.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { ResearchBatch, Source } from "../types.js";
+
+/**
+ * Payload value passed to `interrupt()`. Surfaces as `SseInterruptEvent.payload`
+ * on the wire so the frontend can render the approval UI without an extra fetch.
+ *
+ * Frontend renders this directly; do not include fields that would be unsafe
+ * to expose (e.g. raw DB ids without an authorisation re-check).
+ */
+export interface HumanReviewInterruptPayload {
+  kind: "human_review_research";
+  batch: ResearchBatch | null;
+  pendingSources: Source[];
+}
+
+/**
+ * `human_review_research` node — HITL interrupt point. Halts the graph via
+ * LangGraph `interrupt(payload)` to surface the latest batch + pending sources
+ * to the client; on resume, validates the `{ approvedSourceIds,
+ * rejectedSourceIds?, note? }` payload with {@link researchResumeSchema} and
+ * projects approved/rejected sources into the state.
+ *
+ * HITL 中断ノード本体。`interrupt()` でグラフを停止し、resume 時に
+ * resume payload を検証して `approvedResearch` / `rejectedResearch` を確定する。
+ *
+ * @param state   Current research-loop state.
+ * @param _config LangGraph runnable config (unused but required by the node
+ *                signature).
+ * @returns Partial state update on resume: `{ approvedResearch, rejectedResearch,
+ *          phase: "completed" }`.
+ * @throws  zod `ZodError` if the resume payload is malformed; surfaces as a
+ *          failed run via `GraphRunner`.
+ */
+export async function humanReviewResearch(
+  state: ResearchLoopStateType,
+  _config: LangGraphRunnableConfig,
+): Promise {
+  const latestBatch = state.batches[state.batches.length - 1] ?? null;
+  const payload: HumanReviewInterruptPayload = {
+    kind: "human_review_research",
+    batch: latestBatch,
+    pendingSources: state.pendingSources,
+  };
+
+  // `interrupt(value)` halts execution; the return value is whatever the
+  // resume command (`Command({ resume })`) supplies, which the route layer
+  // builds from `PATCH /resume`'s body.resume field.
+  // interrupt はグラフを停止し、resume 時に再開して値を返す。
+  const resumeValue: unknown = interrupt(payload);
+  const parsed = researchResumeSchema.parse(resumeValue);
+
+  const approvedIds = new Set(parsed.approvedSourceIds);
+  const rejectedIds = new Set(parsed.rejectedSourceIds ?? []);
+  const approvedResearch = state.pendingSources.filter((s) => approvedIds.has(s.id));
+  const rejectedResearch = state.pendingSources.filter((s) => rejectedIds.has(s.id));
+
+  return {
+    approvedResearch,
+    rejectedResearch,
+    phase: "completed",
+  };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/index.ts b/server/api/src/agents/subgraphs/research/nodes/index.ts
new file mode 100644
index 00000000..7c836956
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/index.ts
@@ -0,0 +1,16 @@
+/**
+ * Barrel for research-loop subgraph nodes.
+ *
+ * `researchGraph.ts` から個別ファイルを import せずに済むようにまとめる。
+ * テストでも `vi.mock("...nodes/index.js", { planQueries: vi.fn() ... })`
+ * のように単一の mock point として使う。
+ */
+export { planQueries } from "./planQueries.js";
+export { webSearch } from "./webSearch.js";
+export { wikiSearch } from "./wikiSearch.js";
+export { fetchArticles } from "./fetchArticles.js";
+export { evaluateSufficiency } from "./evaluateSufficiency.js";
+export { refineQueries } from "./refineQueries.js";
+export { compileBatch } from "./compileBatch.js";
+export { humanReviewResearch } from "./humanReviewResearch.js";
+export { shouldRefine } from "../researchGraph.js";
diff --git a/server/api/src/agents/subgraphs/research/nodes/planQueries.ts b/server/api/src/agents/subgraphs/research/nodes/planQueries.ts
new file mode 100644
index 00000000..77d022f9
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/planQueries.ts
@@ -0,0 +1,155 @@
+/**
+ * `plan_queries` — generates the initial query set for the research loop.
+ *
+ * 調査ループの最初のノード。Brief / 指示メッセージから 1〜8 件の調査クエリを
+ * 生成し、`maxIterations` を 1..5 にクランプする。"additional_research" 入力で
+ * 既存セッションの追加調査として呼ばれた場合、`iteration / lastEvaluation /
+ * exitReason` をリセットし、`carryOverApprovedIds` で `pendingSources` を初期化
+ * する（issue #949 の追加調査 API パス）。
+ *
+ * Initial node. Emits a structured query list via `ZediChatModel
+ * .withStructuredOutput`. Honours an "additional_research" input shape so the
+ * same graph id can serve re-runs without a separate route.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { getGraphContext } from "./shared/getGraphContext.js";
+import { dispatchResearchIteration } from "./shared/dispatchSseCustom.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { PlannedQuery, Source } from "../types.js";
+
+/** Default LLM model id for plan/evaluate/refine nodes; overridable by env. */
+const ORCHESTRATOR_MODEL_ENV = "WIKI_COMPOSE_ORCHESTRATOR_MODEL_ID";
+const ORCHESTRATOR_MODEL_FALLBACK = "claude-3-5-haiku";
+
+export function getOrchestratorModelId(): string {
+  return process.env[ORCHESTRATOR_MODEL_ENV]?.trim() || ORCHESTRATOR_MODEL_FALLBACK;
+}
+
+/** Schema for the LLM's structured output. */
+export const planQueriesSchema = z.object({
+  queries: z
+    .array(
+      z.object({
+        query: z.string().min(1),
+        rationale: z.string().optional(),
+        channels: z.array(z.enum(["web", "wiki"])).min(1),
+      }),
+    )
+    .min(1)
+    .max(8),
+});
+
+const SYSTEM_PROMPT =
+  "You are an orchestrator planning research queries for a wiki article. " +
+  "Given the user's brief, propose 1-6 search queries that cover distinct angles. " +
+  "Each query MUST specify at least one channel from ['web','wiki']. " +
+  "Prefer 'wiki' for queries likely answered by the user's own knowledge base " +
+  "and 'web' for queries needing fresh public information. Output JSON only.";
+
+import type { AdditionalResearchRequest } from "../types.js";
+
+function clampMaxIterations(raw: unknown): number {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return 3;
+  const truncated = Math.trunc(raw);
+  return Math.min(Math.max(truncated, 1), 5);
+}
+
+function briefFromState(
+  state: ResearchLoopStateType,
+  additional: AdditionalResearchRequest | null,
+): string {
+  if (additional) {
+    const parts = ["[Additional research request]", additional.instruction];
+    if (additional.brief) parts.push("", "[Original brief]", additional.brief);
+    return parts.join("\n");
+  }
+  // Fall back to concatenating all text content of `messages`. Empty string is
+  // valid — the LLM will still produce default coverage queries.
+  return state.messages
+    .map((m) => {
+      const raw = (m as { content?: unknown }).content;
+      return typeof raw === "string" ? raw : "";
+    })
+    .filter((s) => s.length > 0)
+    .join("\n\n");
+}
+
+/**
+ * `plan_queries` node implementation. Exported for direct unit testing.
+ *
+ * 単体テストから直接呼べるよう export する。
+ */
+export async function planQueries(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const ctx = getGraphContext(config);
+  // Detect additional-research input from the dedicated state field. The route
+  // layer translates `body.input.kind === "additional_research"` into this
+  // shape so LangGraph's strict state schema does not drop unknown top-level
+  // input keys (codex review #956 P1).
+  // 追加調査の検出は state.additionalRequest 専用フィールドで行う。
+  const additional = state.additionalRequest ?? null;
+  const brief = briefFromState(state, additional);
+
+  // Resolve maxIterations: input override > existing state > default(3); clamp 1..5.
+  // maxIterations は既存 state を優先しつつ 1..5 にクランプ。
+  const maxIterations = clampMaxIterations(state.maxIterations ?? 3);
+
+  const model = await createZediChatModel({
+    modelId: getOrchestratorModelId(),
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:plan`,
+    backend: ctx.backend,
+    temperature: 0.4,
+    maxTokens: 1024,
+  });
+  const structured = model.withStructuredOutput(planQueriesSchema, { name: "plan_queries" });
+  const planned = await structured.invoke([
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: brief || "(no brief provided; produce 2 broad coverage queries)" },
+  ]);
+
+  const queries: PlannedQuery[] = planned.queries.map((q) => ({
+    id: randomUUID(),
+    query: q.query,
+    rationale: q.rationale,
+    channels: q.channels,
+  }));
+
+  const carriedSources: Source[] = additional?.carryOverApprovedIds
+    ? additional.carryOverApprovedIds.map((id) => ({
+        id,
+        kind: id.startsWith("wiki:") ? "wiki" : "fetched",
+        title: "(carried over)",
+      }))
+    : [];
+
+  await dispatchResearchIteration(
+    { iteration: 0, status: "planned", queryCount: queries.length },
+    config,
+  );
+
+  const update: ResearchLoopStateUpdate = {
+    queries,
+    maxIterations,
+    iteration: 0,
+    lastEvaluation: null,
+    exitReason: null,
+    phase: "research:plan",
+    // Consume the additional-research seed so a subsequent re-plan inside the
+    // same session (defensive) does not loop on the same instruction.
+    // 追加調査リクエストは 1 度読んだら null にクリアする。
+    additionalRequest: null,
+  };
+  if (additional) {
+    // Additional-research re-run: reset accumulators except for explicit carryover.
+    update.pendingSources = carriedSources;
+  }
+  return update;
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/refineQueries.ts b/server/api/src/agents/subgraphs/research/nodes/refineQueries.ts
new file mode 100644
index 00000000..bbd23663
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/refineQueries.ts
@@ -0,0 +1,92 @@
+/**
+ * `refine_queries` — replaces `queries` with a refined batch based on the
+ * latest evaluation's `missingAspects`. Loops back to `web_search`.
+ *
+ * 直近 evaluation の `missingAspects` を基に次ループのクエリを生成し、
+ * `queries` を全置換する。`iteration` は `evaluate_sufficiency` で既に
+ * post-increment 済みなので、ここでは触らない。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { getGraphContext } from "./shared/getGraphContext.js";
+import { dispatchResearchIteration } from "./shared/dispatchSseCustom.js";
+import { getOrchestratorModelId } from "./planQueries.js";
+import { planQueriesSchema } from "./planQueries.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { PlannedQuery } from "../types.js";
+
+const SYSTEM_PROMPT =
+  "You are refining a research query plan. Given the previous queries, the " +
+  "sources gathered, and the missing aspects flagged by evaluation, propose " +
+  "1-6 NEW queries that fill those gaps. Avoid repeating prior queries. " +
+  "Each query MUST specify at least one channel from ['web','wiki']. " +
+  "Output JSON only.";
+
+function buildUserPrompt(state: ResearchLoopStateType): string {
+  const evaluation = state.lastEvaluation;
+  const missing = evaluation?.missingAspects ?? [];
+  const prior = state.queries.map((q) => `- ${q.query} (${q.channels.join("/")})`);
+  const sourceTitles = state.pendingSources.map((s) => `- [${s.kind}] ${s.title}`);
+  return [
+    `[Iteration ${state.iteration} / ${state.maxIterations}]`,
+    `Previous evaluation score: ${evaluation?.score ?? "n/a"}`,
+    "",
+    "[Missing aspects to address]",
+    ...(missing.length ? missing.map((m) => `- ${m}`) : ["(none flagged; broaden coverage)"]),
+    "",
+    "[Prior queries (avoid duplicates)]",
+    ...prior,
+    "",
+    `[Sources gathered so far: ${state.pendingSources.length}]`,
+    ...sourceTitles,
+  ].join("\n");
+}
+
+/**
+ * `refine_queries` node — replaces `state.queries` with a fresh batch that
+ * addresses `lastEvaluation.missingAspects`, then dispatches
+ * `research_iteration { status: "refined" }`. Loops back to the search
+ * fan-out via the graph edge.
+ *
+ * リファインノード本体。直近の評価結果を元に次イテレーションのクエリを生成する。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (carries `GraphContext` + callbacks).
+ * @returns Partial state update: `{ queries: newQueries, phase }`.
+ */
+export async function refineQueries(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const ctx = getGraphContext(config);
+
+  const model = await createZediChatModel({
+    modelId: getOrchestratorModelId(),
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:refine`,
+    backend: ctx.backend,
+    temperature: 0.5,
+    maxTokens: 1024,
+  });
+  const structured = model.withStructuredOutput(planQueriesSchema, { name: "refine_queries" });
+  const planned = await structured.invoke([
+    { role: "system", content: SYSTEM_PROMPT },
+    { role: "user", content: buildUserPrompt(state) },
+  ]);
+  const queries: PlannedQuery[] = planned.queries.map((q) => ({
+    id: randomUUID(),
+    query: q.query,
+    rationale: q.rationale,
+    channels: q.channels,
+  }));
+
+  await dispatchResearchIteration(
+    { iteration: state.iteration, status: "refined", queryCount: queries.length },
+    config,
+  );
+
+  return { queries, phase: "research:refine" };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/shared/dispatchSseCustom.ts b/server/api/src/agents/subgraphs/research/nodes/shared/dispatchSseCustom.ts
new file mode 100644
index 00000000..02da4b9a
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/shared/dispatchSseCustom.ts
@@ -0,0 +1,58 @@
+/**
+ * Typed wrapper over `dispatchCustomEvent` for the research loop subgraph.
+ *
+ * `dispatchCustomEvent(name, data, config)` を typesafe に呼ぶための薄いラッパ。
+ * `sseMapper` の `mapCustomEvent` がペイロード shape を検証するので、ノード
+ * 側は本ヘルパ経由で型付きで dispatch するだけで良い。
+ */
+import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+
+/** Payload shape for `research_iteration` custom events. */
+export interface ResearchIterationPayload {
+  iteration: number;
+  status: "planned" | "refined";
+  queryCount: number;
+}
+
+/** Payload shape for `research_evaluation` custom events. */
+export interface ResearchEvaluationPayload {
+  iteration: number;
+  score: number;
+  rationale: string;
+  missingAspectsCount: number;
+}
+
+/** Payload shape for `research_batch` custom events. */
+export interface ResearchBatchPayload {
+  batchId: string;
+  iteration: number;
+  sourceCount: number;
+  score: number | null;
+  exitReason: "score_threshold" | "max_iterations";
+}
+
+/**
+ * Per-event helpers. We use 3 narrow functions instead of a generic union so
+ * accidentally swapping payload shapes raises a TS error at the call site.
+ */
+export async function dispatchResearchIteration(
+  payload: ResearchIterationPayload,
+  config: LangGraphRunnableConfig,
+): Promise {
+  await dispatchCustomEvent("research_iteration", payload, config);
+}
+
+export async function dispatchResearchEvaluation(
+  payload: ResearchEvaluationPayload,
+  config: LangGraphRunnableConfig,
+): Promise {
+  await dispatchCustomEvent("research_evaluation", payload, config);
+}
+
+export async function dispatchResearchBatch(
+  payload: ResearchBatchPayload,
+  config: LangGraphRunnableConfig,
+): Promise {
+  await dispatchCustomEvent("research_batch", payload, config);
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/shared/getGraphContext.ts b/server/api/src/agents/subgraphs/research/nodes/shared/getGraphContext.ts
new file mode 100644
index 00000000..4f820f31
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/shared/getGraphContext.ts
@@ -0,0 +1,48 @@
+/**
+ * Tiny helper that pulls the {@link GraphContext} out of LangGraph's
+ * `RunnableConfig.configurable` bag.
+ *
+ * 各ノードが `config.configurable[GRAPH_CONTEXT_CONFIG_KEY]` を引く時の
+ * boilerplate を 1 箇所に寄せるためのユーティリティ。`GraphRunner` が必ず
+ * セットするので production 経路では undefined にならないが、ユニットテスト
+ * で誤って忘れたケースを早期に検出するため throw する。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import {
+  GRAPH_CONTEXT_CONFIG_KEY,
+  type GraphContext,
+} from "../../../../core/types/graphContext.js";
+
+/**
+ * Returns the `GraphContext` injected by `GraphRunner.buildConfig`. Throws
+ * when missing or malformed so misconfigured callers fail loudly with a
+ * pointed error rather than running with default / undefined credentials and
+ * exploding deep inside `createZediChatModel` / `recordUsage`.
+ *
+ * `GraphRunner.buildConfig` が唯一の正規生成者だが、テスト誤用や手動構築の
+ * 防御として、必須フィールドの存在 (`userId`, `db`, `feature`) を浅く検証する。
+ * Zod 等の重い依存は導入しない — 単一のプロデューサで保証している契約への
+ * 二次防衛なので、shape check で十分（coderabbit review #956）。
+ */
+export function getGraphContext(config: LangGraphRunnableConfig | undefined): GraphContext {
+  const configurable = config?.configurable as Record | undefined;
+  const candidate = configurable?.[GRAPH_CONTEXT_CONFIG_KEY];
+  if (!candidate || typeof candidate !== "object") {
+    throw new Error(
+      `Missing GraphContext on config.configurable["${GRAPH_CONTEXT_CONFIG_KEY}"]; ` +
+        "GraphRunner is responsible for populating it.",
+    );
+  }
+  const ctx = candidate as Partial;
+  const missing: string[] = [];
+  if (typeof ctx.userId !== "string" || ctx.userId.length === 0) missing.push("userId");
+  if (!ctx.db) missing.push("db");
+  if (typeof ctx.feature !== "string" || ctx.feature.length === 0) missing.push("feature");
+  if (missing.length > 0) {
+    throw new Error(
+      `GraphContext is missing required fields: ${missing.join(", ")}. ` +
+        "Check GraphRunner.buildConfig.",
+    );
+  }
+  return ctx as GraphContext;
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/webSearch.ts b/server/api/src/agents/subgraphs/research/nodes/webSearch.ts
new file mode 100644
index 00000000..076cecf0
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/webSearch.ts
@@ -0,0 +1,72 @@
+/**
+ * `web_search` node — runs the `webSearchTool` for each query whose channels
+ * include "web". Sources from the tool merge into `pendingSources` via the
+ * reducer's id-keyed dedup.
+ *
+ * web チャンネル指定のクエリごとに `webSearchTool` を並列実行し、結果を
+ * `pendingSources` にマージする。tool 側で `{ ok:false }` が返っても throw せず
+ * skip するので、1 クエリの失敗が iteration を止めない。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { webSearchTool } from "../../../core/tools/webSearch.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { Source } from "../types.js";
+
+interface WebSearchToolEnvelope {
+  ok: boolean;
+  results?: Array<{
+    id: string;
+    kind: "web";
+    title: string;
+    url: string;
+    snippet?: string;
+  }>;
+}
+
+/**
+ * `web_search` node — fans out the `webSearchTool` over every query whose
+ * `channels` include "web". Tool failures are swallowed (skipped) so one bad
+ * query never aborts the iteration.
+ *
+ * web 検索ノード本体。web チャンネル指定のクエリごとに `webSearchTool` を
+ * 並列実行し、結果を `pendingSources` にマージする。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (tool invocation requires it so
+ *               `GraphContext` can flow to the tool).
+ * @returns Partial state update: `{ pendingSources: collectedRows[] }`.
+ */
+export async function webSearch(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const targets = state.queries.filter((q) => q.channels.includes("web"));
+  if (targets.length === 0) return { pendingSources: [] };
+
+  const settled = await Promise.allSettled(
+    targets.map((q) => webSearchTool.invoke({ query: q.query, limit: 5 }, config)),
+  );
+  const collected: Source[] = [];
+  for (const r of settled) {
+    if (r.status !== "fulfilled") continue;
+    const raw = r.value;
+    if (typeof raw !== "string") continue;
+    let envelope: WebSearchToolEnvelope;
+    try {
+      envelope = JSON.parse(raw) as WebSearchToolEnvelope;
+    } catch {
+      continue;
+    }
+    if (!envelope.ok || !envelope.results) continue;
+    for (const hit of envelope.results) {
+      collected.push({
+        id: hit.id,
+        kind: "web",
+        title: hit.title,
+        url: hit.url,
+        snippet: hit.snippet,
+      });
+    }
+  }
+  return { pendingSources: collected };
+}
diff --git a/server/api/src/agents/subgraphs/research/nodes/wikiSearch.ts b/server/api/src/agents/subgraphs/research/nodes/wikiSearch.ts
new file mode 100644
index 00000000..8a38aa79
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/nodes/wikiSearch.ts
@@ -0,0 +1,74 @@
+/**
+ * `wiki_search` node — runs the `wikiSearchTool` for each query whose channels
+ * include "wiki", returning internal page hits with stable `wiki:` ids.
+ *
+ * wiki チャンネル指定のクエリごとに `wikiSearchTool` を並列実行する。
+ * `GraphContext.userId` から所有・受諾済みメンバー・ドメインルールで絞り込む
+ * のは tool 内部で済んでいる（`wikiSearchService.searchUserWikiPages`）。
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { wikiSearchTool } from "../../../core/tools/wikiSearch.js";
+import type { ResearchLoopStateType, ResearchLoopStateUpdate } from "../state.js";
+import type { Source } from "../types.js";
+
+interface WikiSearchToolEnvelope {
+  ok: boolean;
+  results?: Array<{
+    id: string;
+    kind: "wiki";
+    title: string;
+    pageId: string;
+    noteId: string;
+    snippet?: string;
+  }>;
+}
+
+/**
+ * `wiki_search` node — fans out the `wikiSearchTool` over every query whose
+ * `channels` include "wiki". Authorisation (own / accepted-member / domain
+ * rule) is enforced inside the tool via `searchUserWikiPages`, scoped by
+ * `GraphContext.userId` + `userEmail`.
+ *
+ * wiki 検索ノード本体。wiki チャンネル指定のクエリごとに `wikiSearchTool` を
+ * 並列実行し、内部ページのヒットを `pendingSources` にマージする。
+ *
+ * @param state  Current research-loop state.
+ * @param config LangGraph runnable config (tool invocation requires it so
+ *               `GraphContext` can flow to the tool).
+ * @returns Partial state update: `{ pendingSources: collectedRows[] }`.
+ */
+export async function wikiSearch(
+  state: ResearchLoopStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const targets = state.queries.filter((q) => q.channels.includes("wiki"));
+  if (targets.length === 0) return { pendingSources: [] };
+
+  const settled = await Promise.allSettled(
+    targets.map((q) => wikiSearchTool.invoke({ query: q.query, limit: 5 }, config)),
+  );
+  const collected: Source[] = [];
+  for (const r of settled) {
+    if (r.status !== "fulfilled") continue;
+    const raw = r.value;
+    if (typeof raw !== "string") continue;
+    let envelope: WikiSearchToolEnvelope;
+    try {
+      envelope = JSON.parse(raw) as WikiSearchToolEnvelope;
+    } catch {
+      continue;
+    }
+    if (!envelope.ok || !envelope.results) continue;
+    for (const hit of envelope.results) {
+      collected.push({
+        id: hit.id,
+        kind: "wiki",
+        title: hit.title,
+        pageId: hit.pageId,
+        noteId: hit.noteId,
+        snippet: hit.snippet,
+      });
+    }
+  }
+  return { pendingSources: collected };
+}
diff --git a/server/api/src/agents/subgraphs/research/researchGraph.ts b/server/api/src/agents/subgraphs/research/researchGraph.ts
new file mode 100644
index 00000000..15b7ef55
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/researchGraph.ts
@@ -0,0 +1,107 @@
+/**
+ * Wiki Compose P1 — `researchLoopSubgraph` (issue #949).
+ *
+ * 自律調査ループ subgraph。`plan_queries` → `(web_search ∥ wiki_search)` →
+ * `fetch_articles` → `evaluate_sufficiency` を 1 イテレーションとし、
+ * `shouldRefine` の判定で `refine_queries` (= 次ループ) か `compile_batch` →
+ * `human_review_research` (= HITL 中断) のいずれかに分岐する。終了条件:
+ * `score >= 0.75` OR `iteration >= maxIterations` (default 3, clamp 1..5)。
+ *
+ * Cyclic LangGraph with a parallel fan-out (`web_search ∥ wiki_search`) and a
+ * conditional edge after `evaluate_sufficiency`. The HITL stop is implemented
+ * via `interrupt(value)` inside `human_review_research` so the resume payload
+ * (`{ approvedSourceIds, rejectedSourceIds, note }`) flows back into the same
+ * node which projects it into `approvedResearch` / `rejectedResearch`.
+ */
+import { END, START, StateGraph } from "@langchain/langgraph";
+import { ResearchLoopState, type ResearchLoopStateType } from "./state.js";
+import { registerGraph, type GraphFactory } from "../../registry/graphRegistry.js";
+import {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+  humanReviewResearch,
+} from "./nodes/index.js";
+
+/** Registered graph id. */
+export const RESEARCH_GRAPH_ID = "wiki-compose-research" as const;
+/** Registered graph version. Bump when behaviour changes meaningfully. */
+export const RESEARCH_GRAPH_VERSION = "1.0.0";
+
+/**
+ * 終了条件判定。`evaluate_sufficiency` の直後に呼ばれる。
+ *
+ * Conditional edge predicate:
+ * - `score >= 0.75` → `"compile"` (exit loop)
+ * - `iteration >= maxIterations` → `"compile"` (hard cap)
+ * - otherwise → `"refine"` (loop back)
+ *
+ * Pure function; unit-tested directly in `researchGraph.conditional.test.ts`.
+ */
+export function shouldRefine(state: ResearchLoopStateType): "refine" | "compile" {
+  const score = state.lastEvaluation?.score;
+  if (typeof score === "number" && score >= 0.75) return "compile";
+  if (state.iteration >= state.maxIterations) return "compile";
+  return "refine";
+}
+
+const factory: GraphFactory = ({ checkpointer }) => {
+  // LangGraph's `StateGraph` chaining is heavily typed; we let the inference
+  // flow naturally instead of pinning intermediate types, mirroring the stub
+  // graph (`registry/stubGraph.ts`).
+  const builder = new StateGraph(ResearchLoopState)
+    .addNode("plan_queries", planQueries)
+    .addNode("web_search", webSearch)
+    .addNode("wiki_search", wikiSearch)
+    .addNode("fetch_articles", fetchArticles)
+    .addNode("evaluate_sufficiency", evaluateSufficiency)
+    .addNode("refine_queries", refineQueries)
+    .addNode("compile_batch", compileBatch)
+    .addNode("human_review_research", humanReviewResearch)
+    .addEdge(START, "plan_queries")
+    // Parallel fan-out from plan_queries.
+    .addEdge("plan_queries", "web_search")
+    .addEdge("plan_queries", "wiki_search")
+    // Implicit join on fetch_articles (both fan-out branches feed into it).
+    .addEdge("web_search", "fetch_articles")
+    .addEdge("wiki_search", "fetch_articles")
+    .addEdge("fetch_articles", "evaluate_sufficiency")
+    .addConditionalEdges("evaluate_sufficiency", shouldRefine, {
+      refine: "refine_queries",
+      compile: "compile_batch",
+    })
+    // refine_queries kicks the next iteration (loop back via web_search).
+    .addEdge("refine_queries", "web_search")
+    .addEdge("refine_queries", "wiki_search")
+    .addEdge("compile_batch", "human_review_research")
+    .addEdge("human_review_research", END);
+
+  // `checkpointer === false` is honoured by LangGraph as "no persistence" (the
+  // test path), `BaseCheckpointSaver` enables resume in production.
+  return checkpointer ? builder.compile({ checkpointer }) : builder.compile();
+};
+
+/**
+ * Register the research loop graph. Called once at app bootstrap alongside
+ * other graph factories. Idempotent across calls.
+ *
+ * `app.ts` から `registerStubGraph()` と並べて呼ぶ。再登録は registry が
+ * 上書きで吸収する。
+ */
+export function registerResearchLoopGraph(): void {
+  registerGraph({
+    id: RESEARCH_GRAPH_ID,
+    version: RESEARCH_GRAPH_VERSION,
+    phase: "research",
+    description:
+      "Wiki Compose P1: autonomous research loop. Plans queries, runs web + wiki search, " +
+      "fetches articles, evaluates sufficiency, optionally refines and re-loops up to " +
+      "maxIterations (1..5, default 3), then interrupts at human_review_research for " +
+      "HITL source approval. Resume payload: { approvedSourceIds, rejectedSourceIds?, note? }.",
+    factory,
+  });
+}
diff --git a/server/api/src/agents/subgraphs/research/resumeSchema.ts b/server/api/src/agents/subgraphs/research/resumeSchema.ts
new file mode 100644
index 00000000..d94bb7fc
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/resumeSchema.ts
@@ -0,0 +1,33 @@
+/**
+ * Resume payload validator for `human_review_research`.
+ *
+ * `PATCH /api/pages/:pageId/compose-sessions/:id/resume` 経由で送られてくる
+ * `body.resume` のうち、`graphId === "wiki-compose-research"` 向けの shape を
+ * zod で検証する。失敗時は throw され、`graphRunner` が `{ status: "failed" }`
+ * を返して route 層が 4xx を返す。
+ *
+ * Validates the resume payload that the route layer hands to the interrupted
+ * graph. Throws on invalid input so the runner short-circuits to "failed",
+ * preventing partial projections of an ill-formed payload into state.
+ */
+import { z } from "zod";
+
+/**
+ * Resume payload zod schema.
+ *
+ * - `approvedSourceIds` — 必須。空配列も許容（=全 reject）。
+ * - `rejectedSourceIds` — 任意。重複は除去して扱う。
+ * - `note` — 任意の自由記述。HITL 側のメモ用。
+ *
+ * Schema for the human-in-the-loop approval payload. `approvedSourceIds` is
+ * required (empty array means "reject all"); `rejectedSourceIds` defaults to
+ * the empty array; `note` is free-form metadata.
+ */
+export const researchResumeSchema = z.object({
+  approvedSourceIds: z.array(z.string().min(1)).default([]),
+  rejectedSourceIds: z.array(z.string().min(1)).optional().default([]),
+  note: z.string().optional(),
+});
+
+/** Inferred TS type for the parsed resume payload. */
+export type ResearchResumeParsed = z.infer;
diff --git a/server/api/src/agents/subgraphs/research/state.ts b/server/api/src/agents/subgraphs/research/state.ts
new file mode 100644
index 00000000..425459bf
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/state.ts
@@ -0,0 +1,122 @@
+/**
+ * `ResearchLoopState` — LangGraph state for the Wiki Compose research loop (#949).
+ *
+ * 調査ループ subgraph の state。`BaseState` を継承し、ループ制御 (`iteration`,
+ * `maxIterations`, `exitReason`)、調査結果 (`pendingSources`, `batches`)、評価
+ * (`lastEvaluation`)、HITL 結果 (`approvedResearch`, `rejectedResearch`) を持つ。
+ *
+ * Extends `BaseState` with loop control, accumulated sources, evaluation, and
+ * post-interrupt human review output. Reducers favour idempotency:
+ * - `pendingSources` merges by stable `Source.id` so refining the same URL
+ *   upgrades it in place from `kind:"web"` to `kind:"fetched"` instead of
+ *   doubling.
+ * - `batches` appends so the frontend can show a full history.
+ * - All scalar fields use `next ?? prev` so partial updates don't blank state.
+ */
+import { Annotation } from "@langchain/langgraph";
+import { BaseState } from "../../core/state/baseState.js";
+import type {
+  AdditionalResearchRequest,
+  Evaluation,
+  ExitReason,
+  PlannedQuery,
+  ResearchBatch,
+  Source,
+} from "./types.js";
+
+/**
+ * `pendingSources` 用 reducer。id 単位で dedup し、後勝ちで上書きする。
+ * fetch_articles が `web` → `fetched` への昇格をした際にも、同じ id で送ると
+ * 1 行にまとまる。
+ *
+ * Merge sources by `id` with last-write-wins semantics so the loop can upgrade
+ * a `kind:"web"` row to `kind:"fetched"` without duplication. Order is
+ * preserved by first appearance.
+ */
+function mergeSourcesById(prev: Source[], next: Source[] | undefined): Source[] {
+  if (!next || next.length === 0) return prev;
+  const order: string[] = [];
+  const map = new Map();
+  for (const s of prev) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  for (const s of next) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  return order.map((id) => map.get(id) as Source);
+}
+
+/**
+ * Research loop state schema. Subgraph nodes update slices of this.
+ *
+ * 調査ループ state スキーマ。各ノードがこの slice を返して更新する。
+ */
+export const ResearchLoopState = Annotation.Root({
+  ...BaseState.spec,
+
+  /** 現在のループ回数（0 基点。`evaluate_sufficiency` で +1）。 */
+  iteration: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => 0,
+  }),
+  /** ループ回数上限（1..5、デフォルト 3）。`plan_queries` で clamp 確定。 */
+  maxIterations: Annotation({
+    reducer: (prev, next) => next ?? prev,
+    default: () => 3,
+  }),
+  /** 直近のクエリリスト。`plan_queries` / `refine_queries` が全置換する。 */
+  queries: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 蓄積ソース。`mergeSourcesById` で dedup マージ。 */
+  pendingSources: Annotation({
+    reducer: mergeSourcesById,
+    default: () => [],
+  }),
+  /** 直近の評価。 */
+  lastEvaluation: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  /** 終了理由。 */
+  exitReason: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  /** 各ループの compile_batch スナップショット。append。 */
+  batches: Annotation({
+    reducer: (prev, next) => (next === undefined ? prev : [...prev, ...next]),
+    default: () => [],
+  }),
+  /** 採用ソース。`human_review_research` が resume 値から projection する。 */
+  approvedResearch: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 除外ソース。 */
+  rejectedResearch: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /**
+   * 追加調査リクエスト。`POST /run` の `body.input.kind === "additional_research"`
+   * を route 層が詰め直す（LangGraph は未定義の top-level input キーを落とすため
+   * 仲介フィールドが必要）。`plan_queries` が消費後 `null` にクリアする。
+   *
+   * Additional-research seed populated by the route from `body.input`; cleared
+   * to null by `plan_queries` after one read.
+   */
+  additionalRequest: Annotation({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+});
+
+/** `ResearchLoopState.State` のショートカット。 */
+export type ResearchLoopStateType = typeof ResearchLoopState.State;
+
+/** `ResearchLoopState.Update` のショートカット。ノードの戻り値型。 */
+export type ResearchLoopStateUpdate = typeof ResearchLoopState.Update;
diff --git a/server/api/src/agents/subgraphs/research/types.ts b/server/api/src/agents/subgraphs/research/types.ts
new file mode 100644
index 00000000..4db72508
--- /dev/null
+++ b/server/api/src/agents/subgraphs/research/types.ts
@@ -0,0 +1,157 @@
+/**
+ * Shared value types for the Wiki Compose research loop subgraph (#949).
+ *
+ * 調査ループ subgraph の値型。`ResearchLoopState`（{@link ./state.ts}）の
+ * 各フィールドが参照する。
+ *
+ * Pure data types referenced by `ResearchLoopState`. Kept separate from the
+ * `Annotation.Root` definition so node modules can import the types without
+ * pulling LangGraph's runtime symbols into their compilation graph.
+ */
+
+/**
+ * 1 ソースを表す軽量レコード。Web 検索結果 / Wiki 検索結果 / Readability で
+ * 取得した記事本文プレビュー、いずれも同じ shape にまとめる。
+ *
+ * `id` は安定する単一値で、reducer が dedup するキーになる:
+ * - `src:` — web / fetched で **共通** に使う。同じ URL を後段で
+ *   Readability に通すと、reducer (`mergeSourcesById`) が新値で上書きして
+ *   `kind: "web"` → `kind: "fetched"` にインプレース昇格する。リダイレクト後の
+ *   `finalUrl` は別フィールド (`finalUrl`) に格納し、id は常に **元 URL** の
+ *   sha256 で安定させる（codex review #956: URL 正規化の問題対策）。
+ * - `wiki:` — Wiki ページ。pageId 自体が安定 ID なので hash は不要。
+ *
+ * A single research source. Web and fetched share the SAME `id` scheme
+ * (`src:`) so the reducer dedups them across iterations
+ * — fetched literally overwrites the matching web row by id. `finalUrl` is
+ * stored separately so redirect / canonicalisation does not break dedup
+ * (codex review #956).
+ */
+export interface Source {
+  /** Stable id (`src:` for web/fetched, `wiki:` for wiki). */
+  id: string;
+  /** Discriminator. `fetched` upgrades `web` after Readability succeeds. */
+  kind: "web" | "wiki" | "fetched";
+  /** Human-readable title. */
+  title: string;
+  /**
+   * Original URL of the search hit. Present for `web` / `fetched`.
+   * Stable across the loop — `id` is derived from this value, NOT from
+   * `finalUrl`, so redirect URLs do not break id-based dedup.
+   * 元の URL。`fetched` でも `finalUrl` ではなくこちらを id 計算に使う。
+   */
+  url?: string;
+  /**
+   * Post-redirect / Readability-resolved canonical URL.
+   * Present only for `kind === "fetched"`. Used for display / citation; not
+   * used for dedup so a redirect chain does not split a single article into
+   * two state rows.
+   * リダイレクト後の URL（表示・引用用、dedup には使わない）。
+   */
+  finalUrl?: string;
+  /** Snippet from the search result (pre-fetch). */
+  snippet?: string;
+  /** Readability excerpt (post-fetch). Populated for `kind === "fetched"`. */
+  excerpt?: string;
+  /** Internal wiki page id. Populated for `kind === "wiki"`. */
+  pageId?: string;
+  /** Internal wiki note id. Populated for `kind === "wiki"`. */
+  noteId?: string;
+  /** Content hash (sha256 of body). Populated for `kind === "fetched"`. */
+  contentHash?: string;
+  /** ISO timestamp. Populated for `kind === "fetched"`. */
+  fetchedAt?: string;
+}
+
+/**
+ * Orchestrator LLM が組み立てた 1 つの調査クエリ。
+ * `channels` は web / wiki どちらに投げるかを指定する。
+ *
+ * A single planned research query. `channels` decides which search node(s)
+ * the query is dispatched to.
+ */
+export interface PlannedQuery {
+  /** Stable uuid for traceability. */
+  id: string;
+  /** Free-form query string. */
+  query: string;
+  /** Optional model rationale; surfaced for debug only. */
+  rationale?: string;
+  /** Dispatch channels. Non-empty. */
+  channels: Array<"web" | "wiki">;
+}
+
+/**
+ * `evaluate_sufficiency` ノードの出力。`score >= 0.75` で `compile_batch` 側へ
+ * 分岐する（{@link ./researchGraph.ts} の `shouldRefine`）。
+ *
+ * Output of `evaluate_sufficiency`. The conditional edge uses
+ * `score >= 0.75` as the exit predicate.
+ */
+export interface Evaluation {
+  /** 0..1. ≥ 0.75 → exit; otherwise refine. */
+  score: number;
+  /** Short natural-language rationale for the score. */
+  rationale: string;
+  /** Up to 5 short labels for what's still missing. */
+  missingAspects: string[];
+}
+
+/**
+ * `compile_batch` が組み立てる UI 提示用のバッチ。1 ループぶんのスナップショット。
+ *
+ * UI-facing batch produced by `compile_batch`. One per loop iteration; the
+ * frontend reads the latest one when the graph interrupts at
+ * `human_review_research`.
+ */
+export interface ResearchBatch {
+  /** Stable uuid. */
+  id: string;
+  /** Iteration index that produced this batch (0-based). */
+  iteration: number;
+  /** Queries that were dispatched in this iteration. */
+  queries: PlannedQuery[];
+  /** Snapshot of `pendingSources` at compile time. */
+  sources: Source[];
+  /** Last evaluation. `null` only if compile is forced before any evaluate. */
+  evaluation: Evaluation | null;
+  /** ISO timestamp at compile time. */
+  createdAt: string;
+}
+
+/**
+ * ループ終了理由。`compile_batch` で確定し、HITL に渡される。
+ *
+ * Reason the loop exited; set by `compile_batch`.
+ */
+export type ExitReason = "score_threshold" | "max_iterations" | "manual_stop";
+
+/**
+ * `human_review_research` ノードが期待する resume payload の TS 型。
+ * 実体は `resumeSchema.ts` の zod で検証する。
+ *
+ * TS shape of the resume payload accepted by `human_review_research`. The
+ * runtime validator lives in `resumeSchema.ts`.
+ */
+export interface ResearchResumeInput {
+  approvedSourceIds: string[];
+  rejectedSourceIds?: string[];
+  note?: string;
+}
+
+/**
+ * 追加調査リクエスト。`POST /run` の `body.input.kind === "additional_research"`
+ * を route 層が `state.additionalRequest` に詰め替えて graph に渡す。
+ * `plan_queries` が消費した後 `null` にクリアする。
+ *
+ * Additional-research seed. The route translates the documented
+ * `body.input.kind === "additional_research"` payload into this field so
+ * `plan_queries` can detect it from state (LangGraph drops unknown top-level
+ * input keys, so a free-form `kind` field would not survive the boundary).
+ * Cleared to `null` after `plan_queries` consumes it.
+ */
+export interface AdditionalResearchRequest {
+  instruction: string;
+  carryOverApprovedIds?: string[];
+  brief?: string;
+}
diff --git a/server/api/src/app.ts b/server/api/src/app.ts
index 130ba20b..03fc3424 100644
--- a/server/api/src/app.ts
+++ b/server/api/src/app.ts
@@ -45,16 +45,21 @@ import onboardingRoutes from "./routes/onboarding.js";
 import internalRoutes from "./routes/internal.js";
 import composeSessionRoutes from "./routes/composeSessions.js";
 import { registerStubGraph } from "./agents/registry/stubGraph.js";
+import { registerResearchLoopGraph } from "./agents/subgraphs/research/index.js";
 
 /**
  * Creates and configures the Hono API app (routes, CORS, etc.).
  * Hono APIアプリを作成・設定する（ルート・CORS等）。
  */
 export function createApp(): Hono {
-  // Wiki Compose (#948) のスタブグラフを registry に登録する。idempotent。
-  // Register the Wiki Compose P0 smoke-test graph. Idempotent across calls so
-  // hot-reload during dev does not duplicate entries.
+  // Wiki Compose graphs を registry に登録する。いずれも idempotent。
+  // - `wiki-compose-stub` — P0 smoke test (#948)
+  // - `wiki-compose-research` — P1 自律調査ループ (#949)
+  //
+  // Register all Wiki Compose graphs. Both calls are idempotent across hot
+  // reloads (registry uses `Map#set` so the latest registration wins).
   registerStubGraph();
+  registerResearchLoopGraph();
 
   const app = new Hono();
   const wildcard = isWildcardCors();
diff --git a/server/api/src/routes/composeSessions.ts b/server/api/src/routes/composeSessions.ts
index cd15afd1..e4b53de5 100644
--- a/server/api/src/routes/composeSessions.ts
+++ b/server/api/src/routes/composeSessions.ts
@@ -2,8 +2,9 @@
  * `/api/pages/:pageId/compose-sessions` — Wiki Compose session API.
  *
  * Wiki Compose の P0 ルートスケルトン。`wiki_compose_sessions` テーブルの CRUD と、
- * `GraphRunner` 経由でのスタブグラフ実行 (run / resume) を提供する。SSE 形式は
- * `agents/core/types/sseEvents.ts` の `SseEvent` に従う。
+ * `GraphRunner` 経由でのグラフ実行 (run / resume) を提供する。SSE 形式は
+ * `agents/core/types/sseEvents.ts` の `SseEvent` に従う。本ファイル自体は graph
+ * 中立で、入力 / 再開ペイロードの shape は各 graph のノードが zod で検証する。
  *
  * - `POST   /api/pages/:pageId/compose-sessions`              — Create
  * - `GET    /api/pages/:pageId/compose-sessions/:id`          — Read
@@ -11,7 +12,23 @@
  * - `PATCH  /api/pages/:pageId/compose-sessions/:id/resume`   — Resume from interrupt
  * - `DELETE /api/pages/:pageId/compose-sessions/:id`          — Cancel
  *
- * Issue: otomatty/zedi#948
+ * # Per-graph contracts
+ *
+ * `wiki-compose-research` (#949 / P1):
+ * - `POST /run` body.input shapes:
+ *   - Initial run: `{ messages?: [...], maxIterations?: number }` (or any
+ *     object; the graph reads `state.messages` set by LangGraph from
+ *     `body.input`).
+ *   - Additional research (re-run on a *new* session of the same graph id):
+ *     `{ kind: "additional_research", instruction: string, brief?: string,
+ *        carryOverApprovedIds?: string[] }`
+ *     The `plan_queries` node detects this shape, resets the loop, and seeds
+ *     `pendingSources` from `carryOverApprovedIds`.
+ * - `PATCH /resume` body.resume shape:
+ *   `{ approvedSourceIds: string[], rejectedSourceIds?: string[], note?: string }`
+ *   (validated by `researchResumeSchema`; ill-formed payload fails the run.)
+ *
+ * Issue: otomatty/zedi#948 (P0), otomatty/zedi#949 (P1)
  */
 import { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -40,8 +57,54 @@ import {
 import { SSE_EVENT_NAMES, type SseEvent } from "../agents/core/types/sseEvents.js";
 import { GRAPH_CONTEXT_CONFIG_KEY } from "../agents/core/types/graphContext.js";
 import { resolveCheckpointerForRun } from "../agents/core/checkpoint/index.js";
+import { RESEARCH_GRAPH_ID } from "../agents/subgraphs/research/index.js";
 import type { AppEnv } from "../types/index.js";
 
+/**
+ * Translate the documented `body.input.kind === "additional_research"` shape
+ * into a state-compatible payload for the research graph. LangGraph's strict
+ * state schema drops top-level input keys that have no annotation; without
+ * this translation the `kind` / `instruction` / `carryOverApprovedIds` fields
+ * would silently vanish and the loop would behave like a normal initial run.
+ * (codex review #956 P1.)
+ *
+ * For graphs other than `wiki-compose-research`, the input passes through
+ * unchanged.
+ */
+function translateGraphInput(graphId: string, raw: unknown): unknown {
+  if (graphId !== RESEARCH_GRAPH_ID) return raw;
+  if (!raw || typeof raw !== "object") return raw;
+  const r = raw as {
+    kind?: unknown;
+    instruction?: unknown;
+    carryOverApprovedIds?: unknown;
+    brief?: unknown;
+  };
+  if (r.kind !== "additional_research") return raw;
+  const instruction = typeof r.instruction === "string" ? r.instruction : "";
+  const carryOverApprovedIds = Array.isArray(r.carryOverApprovedIds)
+    ? r.carryOverApprovedIds.filter((x): x is string => typeof x === "string")
+    : undefined;
+  const brief = typeof r.brief === "string" ? r.brief : undefined;
+  return {
+    additionalRequest: { instruction, carryOverApprovedIds, brief },
+  };
+}
+
+/**
+ * Per-graph recursion limit. LangGraph's default of 25 is enough for the stub
+ * graph but tight for `wiki-compose-research`, which runs up to ~5 iterations
+ * × ~6 nodes ≈ 30 node executions. We bump it for that graph only rather than
+ * raising the global default at `graphRunner.ts:147`.
+ *
+ * 調査ループは最大 5 イテレーション × 約 6 ノード = ~30 node 実行になり得るため、
+ * 既定の 25 では不足する。該当 graph だけ 60 に引き上げる。
+ */
+function recursionLimitFor(graphId: string): number | undefined {
+  if (graphId === RESEARCH_GRAPH_ID) return 60;
+  return undefined;
+}
+
 const app = new Hono();
 
 /**
@@ -63,7 +126,16 @@ interface RunSessionBody {
 }
 
 interface ResumeSessionBody {
-  /** Interrupt に渡す再開値。HITL の場合は通常ユーザー応答。 */
+  /**
+   * Interrupt に渡す再開値。HITL の場合は通常ユーザー応答。
+   *
+   * Per-graph contract (validated inside the graph's HITL node):
+   * - `wiki-compose-research` (#949):
+   *   `{ approvedSourceIds: string[], rejectedSourceIds?: string[], note?: string }`
+   *
+   * Per-graph contract; the graph node validates the shape and rejects on
+   * mismatch. The route itself is shape-agnostic.
+   */
   resume: unknown;
 }
 
@@ -141,6 +213,7 @@ app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (
   const pageId = c.req.param("pageId");
   const id = c.req.param("id");
   const userId = c.get("userId");
+  const userEmail = c.get("userEmail") ?? null;
   const db = c.get("db");
 
   await assertPageEditAccess(db, pageId, userId);
@@ -241,14 +314,17 @@ app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (
     try {
       await send(startedEvent(id, session.graphId, session.phase));
 
+      const recursionLimit = recursionLimitFor(session.graphId);
       const events = runner.streamEvents(
         {
           graphId: session.graphId,
           checkpointer,
+          ...(recursionLimit !== undefined ? { recursionLimit } : {}),
           context: {
             threadId: id,
             sessionId: id,
             userId,
+            userEmail,
             pageId,
             graphId: session.graphId,
             backend: assertSupportedBackendP0(session.backend),
@@ -257,18 +333,38 @@ app.post("/:pageId/compose-sessions/:id/run", authRequired, rateLimit(), async (
             feature: `wiki_compose:${session.graphId}`,
           },
         },
-        { kind: "input", value: body.input ?? {} },
+        { kind: "input", value: translateGraphInput(session.graphId, body.input ?? {}) },
       );
 
       for await (const raw of events) {
         const ev = raw as LangGraphRuntimeEvent;
         for (const mapped of mapLangGraphEvent(ev)) {
+          // LangGraph ≥ 1.x emits interrupts as a `__interrupt__` field on the
+          // final `on_chain_end` event rather than as a throw; sseMapper turns
+          // those into `SseInterruptEvent` rows. Treat any emitted interrupt
+          // event as terminal — flip status to "interrupted" so the route
+          // persists `closedAt=null` and surfaces resume affordance.
+          // LangGraph 1.x では interrupt は throw されず on_chain_end の output
+          // 内で来る。sseMapper が interrupt SSE に変換するので、ここでは
+          // emitted した時点で finalStatus を interrupted にする。
+          if (mapped.type === "interrupt") {
+            finalStatus = "interrupted";
+          }
           await send(mapped);
         }
       }
 
-      finalStatus = "completed";
+      // Only promote to "completed" if the stream did NOT emit an interrupt
+      // event above. Without this guard, an interrupt detected inside the
+      // for-await loop would be silently overwritten to "completed" once the
+      // stream drains (codex review #956 / coderabbit critical finding).
+      // ストリーム完走時点で interrupted を上書きしないよう、明示的にガードする。
+      if (finalStatus !== "interrupted") {
+        finalStatus = "completed";
+      }
     } catch (err) {
+      // Legacy throw path (LangGraph might re-introduce, version skew etc.).
+      // 古い throw 経路の保険として残す。
       if (isInterruptError(err)) {
         finalStatus = "interrupted";
         await send({ type: "interrupt", payload: extractInterruptPayload(err) });
@@ -297,6 +393,7 @@ app.patch("/:pageId/compose-sessions/:id/resume", authRequired, rateLimit(), asy
   const pageId = c.req.param("pageId");
   const id = c.req.param("id");
   const userId = c.get("userId");
+  const userEmail = c.get("userEmail") ?? null;
   const db = c.get("db");
 
   await assertPageEditAccess(db, pageId, userId);
@@ -351,14 +448,17 @@ app.patch("/:pageId/compose-sessions/:id/resume", authRequired, rateLimit(), asy
 
   let result;
   try {
+    const recursionLimit = recursionLimitFor(session.graphId);
     result = await runner.resume(
       {
         graphId: session.graphId,
         checkpointer,
+        ...(recursionLimit !== undefined ? { recursionLimit } : {}),
         context: {
           threadId: id,
           sessionId: id,
           userId,
+          userEmail,
           pageId,
           graphId: session.graphId,
           backend: assertSupportedBackendP0(session.backend),
diff --git a/server/api/src/routes/search.ts b/server/api/src/routes/search.ts
index d419a60b..16af35df 100644
--- a/server/api/src/routes/search.ts
+++ b/server/api/src/routes/search.ts
@@ -41,8 +41,7 @@ import { Hono } from "hono";
 import { sql } from "drizzle-orm";
 import { authRequired } from "../middleware/auth.js";
 import type { AppEnv } from "../types/index.js";
-import { extractEmailDomain } from "../lib/freeEmailDomains.js";
-import { getDefaultNoteOrNull } from "../services/defaultNoteService.js";
+import { searchUserWikiPages } from "../services/wikiSearchService.js";
 
 function escapeLike(input: string): string {
   return input.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
@@ -79,123 +78,40 @@ app.get("/", authRequired, async (c) => {
   const limit = clampLimit(c.req.query("limit"));
   const pattern = `%${escapeLike(query)}%`;
 
-  // 検索条件用にだけ `content_text` を WHERE に登場させるが、SELECT には含めない。
-  // SELECT に流すと API 経由でページ本文が丸ごと露出し得る（PR #873 review:
-  // CodeRabbit）。クライアントが消費するのは `content_preview` のみ。
+  // ページ検索は `services/wikiSearchService.ts` に切り出した純粋関数を経由する。
+  // SQL は元 route と同一を維持しつつ、tool / subgraph (#949) からも再利用可能に
+  // するための移譲。`content_text` を SELECT に出さないポリシー、scope=shared での
+  // owner / accepted member / domain rule 結合、`scope=own` の default-note 絞り込み
+  // はすべて service 側で踏襲する。
   //
-  // `content_text` is used in the WHERE clause for matching but is NOT in the
-  // SELECT list — otherwise the API would leak full page bodies (PR #873 review:
-  // CodeRabbit). Clients only consume `content_preview`.
-  const searchColumns = sql`p.id, p.title, p.content_preview, p.updated_at, p.note_id`;
-
-  const normalizedEmail = typeof userEmailRaw === "string" ? userEmailRaw.trim().toLowerCase() : "";
-  const emailDomain = extractEmailDomain(normalizedEmail);
-
-  const domainPredicate =
-    emailDomain !== null
-      ? sql`OR EXISTS (
-          SELECT 1
-          FROM notes n
-          INNER JOIN note_domain_access nda ON nda.note_id = n.id
-          WHERE n.id = p.note_id
-            AND n.is_deleted = false
-            AND nda.is_deleted = false
-            AND nda.domain = ${emailDomain}
-        )`
-      : sql``;
-
-  let pageRows: unknown[] = [];
-
-  if (scope === "shared") {
-    const sharedResults = await db.execute(sql`
-      SELECT ${searchColumns}
-      FROM pages p
-      LEFT JOIN page_contents pc ON pc.page_id = p.id
-      WHERE p.is_deleted = false
-        AND (
-          EXISTS (
-            SELECT 1 FROM notes n
-            WHERE n.id = p.note_id AND n.is_deleted = false AND n.owner_id = ${userId}
-          )
-          OR EXISTS (
-            SELECT 1
-            FROM notes n
-            INNER JOIN note_members nm ON nm.note_id = n.id
-            INNER JOIN "user" u ON LOWER(u.email) = LOWER(nm.member_email)
-            WHERE n.id = p.note_id
-              AND u.id = ${userId}
-              AND nm.status = 'accepted'
-              AND nm.is_deleted = false
-              AND n.is_deleted = false
-          )
-          ${domainPredicate}
-        )
-        AND (
-          p.title ILIKE ${pattern}
-          OR pc.content_text ILIKE ${pattern}
-        )
-      ORDER BY p.updated_at DESC
-      LIMIT ${limit}
-    `);
-    pageRows = sharedResults.rows;
-  } else {
-    const defaultNote = await getDefaultNoteOrNull(db, userId);
-    if (!defaultNote) {
-      // デフォルトノートが無い場合でもハイライト検索は走り得るので、ページ部だけ空配列に。
-      // Even without a default note, highlight search can still run, so only the
-      // page branch short-circuits here.
-      const highlightRows = await runPdfHighlightSearch(db, userId, pattern, limit);
-      return c.json({ results: highlightRows });
-    }
-    const ownResults = await db.execute(sql`
-      SELECT ${searchColumns}
-      FROM pages p
-      LEFT JOIN page_contents pc ON pc.page_id = p.id
-      WHERE p.is_deleted = false
-        AND p.note_id = ${defaultNote.id}
-        AND (
-          p.title ILIKE ${pattern}
-          OR pc.content_text ILIKE ${pattern}
-        )
-      ORDER BY p.updated_at DESC
-      LIMIT ${limit}
-    `);
-    pageRows = ownResults.rows;
-  }
-
-  // 契約フィールドのみを明示マップして response に流す。SQL の SELECT に直接含まれない
-  // カラム (owner_id / thumbnail_url / source_url) は明示的に null/undefined で埋めて
-  // 型 (`SearchPageResultRow`) との整合を取る。raw row を spread で流すと将来 SELECT
-  // を増やしたとき静かに API が漏れるので、PR #873 review (CodeRabbit) で明示化した。
-  //
-  // Map only the contracted fields explicitly. We do not spread raw SQL rows
-  // because any future SELECT addition would silently widen the API payload
-  // (PR #873 review: CodeRabbit). Columns not in the current SELECT are
-  // emitted as `null`/`undefined` to stay aligned with `SearchPageResultRow`.
-  const taggedPageRows = pageRows.map((row) => {
-    const r = row as {
-      id: string;
-      note_id: string;
-      title: string | null;
-      content_preview: string | null;
-      updated_at: string;
-    };
-    return {
-      kind: "page" as const,
-      id: r.id,
-      note_id: r.note_id,
-      // `owner_id` / `thumbnail_url` / `source_url` は将来 SELECT に追加する想定の
-      // プレースホルダ。現状の SQL では返らないので明示的に null/undefined を入れる。
-      // Placeholders for columns not yet in SELECT; emitted explicitly so the
-      // payload shape stays stable for the discriminated union.
-      owner_id: null,
-      title: r.title,
-      content_preview: r.content_preview,
-      thumbnail_url: null,
-      source_url: null,
-      updated_at: r.updated_at,
-    };
-  });
+  // Page search is delegated to `wikiSearchService.searchUserWikiPages` so the
+  // research-loop subgraph (#949) can call the same data set without going
+  // through Hono context. The SQL is preserved verbatim; the previously-reviewed
+  // safety properties (no full body in SELECT, default-note scoping, domain
+  // predicate) live in the service module now.
+  const userEmail = typeof userEmailRaw === "string" ? userEmailRaw : null;
+  const pageHits =
+    scope === "shared"
+      ? await searchUserWikiPages(db, userId, userEmail, query, "shared", limit)
+      : await searchUserWikiPages(db, userId, userEmail, query, "own", limit);
+
+  // `scope=own` でデフォルトノートが無いユーザーは pageHits === [] になる。
+  // ハイライト検索は所有さえあれば走り得るので、ページ無しでも続行する。
+  // For `scope=own` with no default note, `pageHits` is empty; highlight search
+  // is still meaningful since highlights are owner-keyed.
+  const taggedPageRows = pageHits.map((hit) => ({
+    kind: "page" as const,
+    id: hit.pageId,
+    note_id: hit.noteId,
+    // `owner_id` / `thumbnail_url` / `source_url` は将来 SELECT に追加する想定の
+    // プレースホルダ。Placeholders for columns not yet in SELECT.
+    owner_id: null,
+    title: hit.title,
+    content_preview: hit.contentPreview,
+    thumbnail_url: null,
+    source_url: null,
+    updated_at: hit.updatedAt,
+  }));
 
   const highlightRows = await runPdfHighlightSearch(db, userId, pattern, limit);
 
diff --git a/server/api/src/services/wikiSearchService.ts b/server/api/src/services/wikiSearchService.ts
new file mode 100644
index 00000000..1c0de948
--- /dev/null
+++ b/server/api/src/services/wikiSearchService.ts
@@ -0,0 +1,175 @@
+/**
+ * Wiki ページ ILIKE 検索サービス。
+ *
+ * `routes/search.ts` (`/api/search`) のページ検索ロジックを純粋関数として
+ * 切り出したもの。Hono コンテキストへの依存を消し、tool / subgraph から
+ * `db` / `userId` / `userEmail` を引数で受け取れるようにする。SQL は元 route
+ * と一致させ、CodeRabbit / codex の review 指摘 (PR #873) が指す
+ * - 「`content_text` を SELECT に晒さない」
+ * - 「呼び出し元 default note への絞り込み」
+ * - 「scope=shared での owner / accepted member / domain rule 結合」
+ * をすべて踏襲する。
+ *
+ * Pure service version of the page-search branch in `routes/search.ts`. The
+ * route remains the HTTP entry point, but tools (`wikiSearchTool` for the
+ * Wiki Compose research subgraph, #949) need to query the same data set
+ * without going through Hono context. The SQL itself is held identical to the
+ * route so the previously-reviewed safety properties (no full body in SELECT,
+ * domain-rule support, default-note scoping) carry over.
+ */
+import { sql } from "drizzle-orm";
+import type { Database } from "../types/index.js";
+import { extractEmailDomain } from "../lib/freeEmailDomains.js";
+import { getDefaultNoteOrNull } from "./defaultNoteService.js";
+
+/**
+ * 検索スコープ。`own` は呼び出し元のデフォルトノート配下のページのみ、
+ * `shared` はアクセス可能な全ノート横断（route のスコープ契約と同じ）。
+ *
+ * Scope contract mirrors `/api/search?scope=...`:
+ * - `own`: pages under the caller's default note only.
+ * - `shared`: pages across any note the caller can access (owner, accepted
+ *   member, or domain rule).
+ */
+export type WikiSearchScope = "own" | "shared";
+
+/**
+ * 1 件の検索ヒット。ページ ID + ノート ID + タイトル + 抜粋。
+ *
+ * One search hit. snake_case is intentional in {@link Source} but here we use
+ * camelCase to keep the service Pure-TS-shaped; the caller (tool / subgraph)
+ * remaps to whatever wire format it wants.
+ */
+export interface WikiSearchHit {
+  pageId: string;
+  noteId: string;
+  title: string | null;
+  contentPreview: string | null;
+  updatedAt: string;
+}
+
+/**
+ * 内部用: ILIKE 用に `%` `_` `\` をエスケープする。
+ *
+ * Escape SQL LIKE meta-characters so user input is treated as a literal.
+ */
+function escapeLike(input: string): string {
+  return input.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+}
+
+/**
+ * ユーザーの Wiki ページを ILIKE で検索する。空クエリは空配列を返す。
+ *
+ * Search the user's wiki pages by ILIKE. Empty query returns an empty array.
+ * `limit` is clamped to 1..100 to match the route behaviour.
+ *
+ * @param db        Drizzle DB ハンドル。
+ * @param userId    実行ユーザー ID。
+ * @param userEmail 実行ユーザーのメール（`shared` スコープでドメインルール
+ *                  予測子に使う。null なら domain predicate を出さない）。
+ * @param query     検索クエリ。`%` / `_` は自動エスケープ。
+ * @param scope     "own" or "shared"（既定 "shared"）。
+ * @param limit     最大件数 (default 10, max 100)。
+ */
+export async function searchUserWikiPages(
+  db: Database,
+  userId: string,
+  userEmail: string | null,
+  query: string,
+  scope: WikiSearchScope = "shared",
+  limit = 10,
+): Promise {
+  const trimmed = query.trim();
+  if (!trimmed) return [];
+
+  const safeLimit = Math.min(Math.max(Math.trunc(limit), 1), 100);
+  const pattern = `%${escapeLike(trimmed)}%`;
+
+  // `content_text` を WHERE には残しつつ SELECT に出さない方針は route と同じ
+  // (#873 review)。プレビューは `content_preview` カラムを返す。
+  const searchColumns = sql`p.id, p.title, p.content_preview, p.updated_at, p.note_id`;
+
+  if (scope === "own") {
+    const defaultNote = await getDefaultNoteOrNull(db, userId);
+    if (!defaultNote) return [];
+    const result = await db.execute(sql`
+      SELECT ${searchColumns}
+      FROM pages p
+      LEFT JOIN page_contents pc ON pc.page_id = p.id
+      WHERE p.is_deleted = false
+        AND p.note_id = ${defaultNote.id}
+        AND (
+          p.title ILIKE ${pattern}
+          OR pc.content_text ILIKE ${pattern}
+        )
+      ORDER BY p.updated_at DESC
+      LIMIT ${safeLimit}
+    `);
+    return result.rows.map(rowToHit);
+  }
+
+  const normalizedEmail = typeof userEmail === "string" ? userEmail.trim().toLowerCase() : "";
+  const emailDomain = extractEmailDomain(normalizedEmail);
+
+  const domainPredicate =
+    emailDomain !== null
+      ? sql`OR EXISTS (
+          SELECT 1
+          FROM notes n
+          INNER JOIN note_domain_access nda ON nda.note_id = n.id
+          WHERE n.id = p.note_id
+            AND n.is_deleted = false
+            AND nda.is_deleted = false
+            AND nda.domain = ${emailDomain}
+        )`
+      : sql``;
+
+  const result = await db.execute(sql`
+    SELECT ${searchColumns}
+    FROM pages p
+    LEFT JOIN page_contents pc ON pc.page_id = p.id
+    WHERE p.is_deleted = false
+      AND (
+        EXISTS (
+          SELECT 1 FROM notes n
+          WHERE n.id = p.note_id AND n.is_deleted = false AND n.owner_id = ${userId}
+        )
+        OR EXISTS (
+          SELECT 1
+          FROM notes n
+          INNER JOIN note_members nm ON nm.note_id = n.id
+          INNER JOIN "user" u ON LOWER(u.email) = LOWER(nm.member_email)
+          WHERE n.id = p.note_id
+            AND u.id = ${userId}
+            AND nm.status = 'accepted'
+            AND nm.is_deleted = false
+            AND n.is_deleted = false
+        )
+        ${domainPredicate}
+      )
+      AND (
+        p.title ILIKE ${pattern}
+        OR pc.content_text ILIKE ${pattern}
+      )
+      ORDER BY p.updated_at DESC
+      LIMIT ${safeLimit}
+  `);
+  return result.rows.map(rowToHit);
+}
+
+function rowToHit(row: unknown): WikiSearchHit {
+  const r = row as {
+    id: string;
+    note_id: string;
+    title: string | null;
+    content_preview: string | null;
+    updated_at: string;
+  };
+  return {
+    pageId: r.id,
+    noteId: r.note_id,
+    title: r.title,
+    contentPreview: r.content_preview,
+    updatedAt: r.updated_at,
+  };
+}

From 94400b99d1cf756987c2066ad3e0a133ab9ccbc4 Mon Sep 17 00:00:00 2001
From: Akimasa Sugai <119780981+otomatty@users.noreply.github.com>
Date: Mon, 25 May 2026 07:26:21 +0900
Subject: [PATCH 19/44] =?UTF-8?q?feat:=20wiki=20compose=20P2=20=E2=80=94?=
 =?UTF-8?q?=20full=20orchestrator=20graph=20+=20split-screen=20UI=20(#950)?=
 =?UTF-8?q?=20(#959)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Backend (server/api/src/agents/graphs/wikiCompose/):
- wikiComposeGraph orchestrator that walks Brief → Research → Structure
  → Draft → Completed in one LangGraph. State extends ResearchLoopState as a
  strict superset so the P1 research loop composes inline; interrupts at the
  three HITL points (brief / research / outline) halt the same thread_id.
- new nodes: briefDialogue (0..7 structured questions), humanReviewBrief,
  structureDialogue (3..10 section outline), humanReviewOutline, draftSections
  (sequential per-section LLM streaming via model.stream), completed
  (markdown assembly + citation collation).
- resume payload validators (briefResumeSchema, outlineResumeSchema) reject
  malformed payloads at the node boundary.
- new SSE events compose_phase / compose_section so the frontend can drive
  the phase stepper + per-section streaming without inspecting state.
- composeSessions route bumps recursion limit to 120 for the orchestrator
  (Brief + Research up to 5x6 nodes + Structure + up to 10 draft sections).

Frontend (src/):
- /notes/:noteId/:pageId/compose and /compose/:sessionId routes mount the new
  WikiComposePage (split-screen: left EditorPane with live section preview,
  right ComposePanel with PhaseStepper + Brief/Research/Outline sections +
  Activity timeline). Mobile uses vertical split.
- useWikiComposeSession hook owns the SSE wiring and state machine.
- composeService provides REST + SSE clients with a spec-compliant SSE parser
  (handles multi-chunk records, comments, multi-line data, aborts).
- WikiGeneratorButton gains a composeHref mode that navigates to /compose and
  stays visible on pages that already have content (Compose supports append).
  Legacy inline-generation path unchanged when composeHref is absent.

Tests:
- vitest: orchestrator wiring + 3 interrupt points pinned with MemorySaver;
  SSE custom-event mapper extensions; SSE parser edge cases; hook state
  reductions for Brief / Draft / submitBrief flows; PhaseStepper a11y.
- playwright (e2e/wiki-compose.spec.ts): full happy-path with mocked SSE
  routes — Compose entry → Brief submit → research approval → outline
  approval → completed Draft → back to /notes.

Issue: otomatty/zedi#950

Co-authored-by: Claude 
---
 e2e/wiki-compose.spec.ts                      | 314 +++++++++++
 .../wikiCompose/wikiComposeGraph.test.ts      | 288 ++++++++++
 .../__tests__/agents/runner/sseMapper.test.ts |  44 ++
 server/api/src/agents/core/types/sseEvents.ts |  45 +-
 .../src/agents/graphs/wikiCompose/index.ts    |  37 ++
 .../graphs/wikiCompose/nodes/briefDialogue.ts | 150 ++++++
 .../graphs/wikiCompose/nodes/completed.ts     |  66 +++
 .../graphs/wikiCompose/nodes/draftSections.ts | 239 +++++++++
 .../wikiCompose/nodes/humanReviewBrief.ts     |  91 ++++
 .../wikiCompose/nodes/humanReviewOutline.ts   |  46 ++
 .../agents/graphs/wikiCompose/nodes/index.ts  |  12 +
 .../wikiCompose/nodes/shared/dispatch.ts      |  41 ++
 .../nodes/shared/loadPageSnapshot.ts          |  54 ++
 .../wikiCompose/nodes/structureDialogue.ts    | 135 +++++
 .../graphs/wikiCompose/resumeSchemas.ts       |  66 +++
 .../src/agents/graphs/wikiCompose/state.ts    | 195 +++++++
 .../src/agents/graphs/wikiCompose/types.ts    | 212 ++++++++
 .../graphs/wikiCompose/wikiComposeGraph.ts    | 141 +++++
 server/api/src/agents/index.ts                |  24 +
 server/api/src/agents/runner/sseMapper.ts     |  40 ++
 server/api/src/app.ts                         |   5 +-
 server/api/src/routes/composeSessions.ts      |  10 +-
 src/App.tsx                                   |   9 +
 src/components/editor/WikiGeneratorButton.tsx |  46 +-
 src/components/note/PageEditorContent.tsx     |  25 +-
 .../wikiCompose/ActivitySection.tsx           |  89 ++++
 .../wikiCompose/BriefQuestionCard.tsx         | 102 ++++
 src/components/wikiCompose/ComposePanel.tsx   | 110 ++++
 .../wikiCompose/DialogueSection.tsx           | 238 +++++++++
 src/components/wikiCompose/EditorPane.tsx     | 100 ++++
 src/components/wikiCompose/OutlineEditor.tsx  | 170 ++++++
 .../wikiCompose/PhaseStepper.test.tsx         |  25 +
 src/components/wikiCompose/PhaseStepper.tsx   |  66 +++
 .../wikiCompose/ResearchSection.tsx           | 234 +++++++++
 src/hooks/useWikiComposeSession.test.ts       | 160 ++++++
 src/hooks/useWikiComposeSession.ts            | 493 ++++++++++++++++++
 src/lib/wikiCompose/composeService.test.ts    | 133 +++++
 src/lib/wikiCompose/composeService.ts         | 257 +++++++++
 src/lib/wikiCompose/types.ts                  | 188 +++++++
 src/pages/NotePageView.tsx                    |   6 +
 src/pages/WikiComposePage.tsx                 | 186 +++++++
 41 files changed, 4878 insertions(+), 14 deletions(-)
 create mode 100644 e2e/wiki-compose.spec.ts
 create mode 100644 server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeGraph.test.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/index.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/briefDialogue.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/completed.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/draftSections.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/humanReviewBrief.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/humanReviewOutline.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/index.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/shared/dispatch.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/shared/loadPageSnapshot.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/nodes/structureDialogue.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/resumeSchemas.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/state.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/types.ts
 create mode 100644 server/api/src/agents/graphs/wikiCompose/wikiComposeGraph.ts
 create mode 100644 src/components/wikiCompose/ActivitySection.tsx
 create mode 100644 src/components/wikiCompose/BriefQuestionCard.tsx
 create mode 100644 src/components/wikiCompose/ComposePanel.tsx
 create mode 100644 src/components/wikiCompose/DialogueSection.tsx
 create mode 100644 src/components/wikiCompose/EditorPane.tsx
 create mode 100644 src/components/wikiCompose/OutlineEditor.tsx
 create mode 100644 src/components/wikiCompose/PhaseStepper.test.tsx
 create mode 100644 src/components/wikiCompose/PhaseStepper.tsx
 create mode 100644 src/components/wikiCompose/ResearchSection.tsx
 create mode 100644 src/hooks/useWikiComposeSession.test.ts
 create mode 100644 src/hooks/useWikiComposeSession.ts
 create mode 100644 src/lib/wikiCompose/composeService.test.ts
 create mode 100644 src/lib/wikiCompose/composeService.ts
 create mode 100644 src/lib/wikiCompose/types.ts
 create mode 100644 src/pages/WikiComposePage.tsx

diff --git a/e2e/wiki-compose.spec.ts b/e2e/wiki-compose.spec.ts
new file mode 100644
index 00000000..8f7d696f
--- /dev/null
+++ b/e2e/wiki-compose.spec.ts
@@ -0,0 +1,314 @@
+/**
+ * Wiki Compose P2 happy-path E2E (issue #950).
+ *
+ * Compose の入口 → brief → 調査確認 → 構成 → 執筆 → 完了の流れを Playwright で
+ * 検証する。実 LLM / 実 API は使わず、`page.route` で `/api/pages/.../compose-sessions`
+ * 系を全てモックして wire 形式 (SSE) を再生する。
+ *
+ * Drives the Compose split-screen UI through every interrupt point using a
+ * fully mocked SSE stream. Pins both the wire contract (the UI consumes the
+ * SSE shapes correctly) and the user-facing happy path without depending on
+ * a running API backend with real LLM access.
+ */
+import { test, expect } from "./auth-mock";
+import type { Page, Route } from "@playwright/test";
+
+const NOTE_ID = "11111111-1111-4111-8111-111111111111";
+const PAGE_ID = "22222222-2222-4222-8222-222222222222";
+const SESSION_ID = "33333333-3333-4333-8333-333333333333";
+
+const PAGE_SNAPSHOT = {
+  pageId: PAGE_ID,
+  title: "Photosynthesis",
+  body: "",
+  hasContent: false,
+};
+
+const BRIEF_QUESTION_ID = "qid-1";
+const BRIEF_OPTION_ID = "oid-1";
+const SOURCE_ID = "src:demo";
+const SECTION_ID = "sec-overview";
+
+/**
+ * Encode a sequence of SSE-formatted events as a Uint8Array body. Each event
+ * gets `event:` + `data:` lines and a blank-line terminator.
+ */
+function sseBody(events: Array<{ type: string; payload: unknown }>): Uint8Array {
+  const parts = events.map(
+    ({ type, payload }) => `event: ${type}\ndata: ${JSON.stringify(payload)}\n\n`,
+  );
+  return new TextEncoder().encode(parts.join(""));
+}
+
+let runCount = 0;
+
+/** Per-run event sequences served by the mocked SSE endpoint. */
+function eventsForRun(n: number): Array<{ type: string; payload: unknown }> {
+  // Run 1: initial run → halt at Brief interrupt.
+  // Run 2: after Brief resume → halt at Research interrupt.
+  // Run 3: after Research resume → halt at Outline interrupt.
+  // Run 4: after Outline resume → stream Draft and complete.
+  switch (n) {
+    case 1:
+      return [
+        {
+          type: "started",
+          payload: { type: "started", sessionId: SESSION_ID, graphId: "wiki-compose" },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "brief", status: "entered" },
+        },
+        {
+          type: "interrupt",
+          payload: {
+            type: "interrupt",
+            payload: {
+              kind: "human_review_brief",
+              questions: [
+                {
+                  id: BRIEF_QUESTION_ID,
+                  question: "What's the audience for this article?",
+                  rationale: "Helps the agent calibrate depth.",
+                  required: false,
+                  options: [
+                    { id: BRIEF_OPTION_ID, label: "General readers" },
+                    { id: "oid-2", label: "Specialists" },
+                  ],
+                },
+              ],
+              pageSnapshot: PAGE_SNAPSHOT,
+            },
+          },
+        },
+        { type: "done", payload: { type: "done", status: "interrupted" } },
+      ];
+    case 2:
+      return [
+        {
+          type: "started",
+          payload: { type: "started", sessionId: SESSION_ID, graphId: "wiki-compose" },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "research", status: "entered" },
+        },
+        {
+          type: "interrupt",
+          payload: {
+            type: "interrupt",
+            payload: {
+              kind: "human_review_research",
+              batch: {
+                id: "batch-1",
+                iteration: 0,
+                queries: [],
+                sources: [],
+                evaluation: null,
+                createdAt: new Date().toISOString(),
+              },
+              pendingSources: [
+                {
+                  id: SOURCE_ID,
+                  kind: "web",
+                  title: "Photosynthesis — Britannica",
+                  url: "https://example.com/photosynthesis",
+                  snippet: "Photosynthesis converts light energy…",
+                },
+              ],
+            },
+          },
+        },
+        { type: "done", payload: { type: "done", status: "interrupted" } },
+      ];
+    case 3:
+      return [
+        {
+          type: "started",
+          payload: { type: "started", sessionId: SESSION_ID, graphId: "wiki-compose" },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "structure", status: "entered" },
+        },
+        {
+          type: "interrupt",
+          payload: {
+            type: "interrupt",
+            payload: {
+              kind: "human_review_outline",
+              outline: [
+                {
+                  id: SECTION_ID,
+                  heading: "Overview",
+                  depth: 1,
+                  intent: "Brief introduction",
+                },
+              ],
+              approvedSources: [
+                {
+                  id: SOURCE_ID,
+                  kind: "web",
+                  title: "Photosynthesis — Britannica",
+                  url: "https://example.com/photosynthesis",
+                  snippet: "Photosynthesis converts light energy…",
+                },
+              ],
+            },
+          },
+        },
+        { type: "done", payload: { type: "done", status: "interrupted" } },
+      ];
+    case 4:
+      return [
+        {
+          type: "started",
+          payload: { type: "started", sessionId: SESSION_ID, graphId: "wiki-compose" },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "draft", status: "entered" },
+        },
+        {
+          type: "compose_section",
+          payload: {
+            type: "compose_section",
+            sectionId: SECTION_ID,
+            heading: "Overview",
+            status: "started",
+            index: 1,
+            total: 1,
+          },
+        },
+        { type: "token", payload: { type: "token", node: "draft_sections", content: "Photo" } },
+        {
+          type: "token",
+          payload: { type: "token", node: "draft_sections", content: "synthesis." },
+        },
+        {
+          type: "compose_section",
+          payload: {
+            type: "compose_section",
+            sectionId: SECTION_ID,
+            heading: "Overview",
+            status: "completed",
+            index: 1,
+            total: 1,
+          },
+        },
+        {
+          type: "compose_phase",
+          payload: { type: "compose_phase", phase: "completed", status: "entered" },
+        },
+        { type: "done", payload: { type: "done", status: "completed" } },
+      ];
+    default:
+      return [{ type: "done", payload: { type: "done", status: "completed" } }];
+  }
+}
+
+/** Install the Compose API mocks (create / get / run / resume / cancel). */
+async function installComposeMocks(page: Page): Promise {
+  runCount = 0;
+
+  // POST /compose-sessions — create.
+  await page.route(`**/api/pages/${PAGE_ID}/compose-sessions`, async (route: Route) => {
+    if (route.request().method() === "POST") {
+      await route.fulfill({
+        status: 201,
+        contentType: "application/json",
+        body: JSON.stringify({
+          session: {
+            id: SESSION_ID,
+            pageId: PAGE_ID,
+            userId: "user-1",
+            graphId: "wiki-compose",
+            backend: "zedi_managed",
+            phase: "init",
+            status: "pending",
+            metadata: null,
+            lastError: null,
+            closedAt: null,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+          },
+        }),
+      });
+      return;
+    }
+    await route.fallback();
+  });
+
+  // POST /compose-sessions/:id/run — SSE.
+  await page.route(
+    `**/api/pages/${PAGE_ID}/compose-sessions/${SESSION_ID}/run`,
+    async (route: Route) => {
+      runCount += 1;
+      const body = sseBody(eventsForRun(runCount));
+      await route.fulfill({
+        status: 200,
+        headers: { "content-type": "text/event-stream", "cache-control": "no-cache" },
+        body: Buffer.from(body),
+      });
+    },
+  );
+
+  // PATCH /compose-sessions/:id/resume.
+  await page.route(
+    `**/api/pages/${PAGE_ID}/compose-sessions/${SESSION_ID}/resume`,
+    async (route: Route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({ status: "interrupted", output: null }),
+      });
+    },
+  );
+}
+
+test.describe("Wiki Compose P2 happy path", () => {
+  test.setTimeout(60_000);
+
+  test("walks Brief → Research → Outline → Draft → Completed", async ({ page }) => {
+    await installComposeMocks(page);
+
+    await page.goto(`/notes/${NOTE_ID}/${PAGE_ID}/compose`);
+
+    // Brief interrupt — question card appears.
+    const briefCard = page.getByTestId(`brief-card-${BRIEF_QUESTION_ID}`);
+    await expect(briefCard).toBeVisible();
+    await expect(page.getByText("What's the audience for this article?")).toBeVisible();
+
+    // Pick an option and submit.
+    await page.getByTestId(`brief-option-${BRIEF_OPTION_ID}`).click();
+    await page.getByTestId("submit-brief").click();
+
+    // Research interrupt — source review card appears.
+    const sourceRow = page.getByTestId(`source-row-${SOURCE_ID}`);
+    await expect(sourceRow).toBeVisible({ timeout: 10000 });
+
+    // Approve all sources and continue.
+    await page.getByTestId("research-submit").click();
+
+    // Outline interrupt — outline row appears.
+    const outlineRow = page.getByTestId(`outline-row-${SECTION_ID}`);
+    await expect(outlineRow).toBeVisible({ timeout: 10000 });
+
+    // Approve outline and continue.
+    await page.getByTestId("outline-submit").click();
+
+    // Draft phase — phase stepper advances to completed and the editor pane
+    // renders the streamed body.
+    await expect(page.getByTestId("phase-step-completed")).toHaveAttribute("aria-current", "step", {
+      timeout: 10000,
+    });
+    await expect(page.getByTestId(`editor-section-${SECTION_ID}`)).toContainText(
+      "Photosynthesis.",
+      { timeout: 10000 },
+    );
+
+    // Back button returns to the page.
+    await page.getByTestId("compose-back").click();
+    await expect(page).toHaveURL(`/notes/${NOTE_ID}/${PAGE_ID}`);
+  });
+});
diff --git a/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeGraph.test.ts b/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeGraph.test.ts
new file mode 100644
index 00000000..bd2d6c0c
--- /dev/null
+++ b/server/api/src/__tests__/agents/graphs/wikiCompose/wikiComposeGraph.test.ts
@@ -0,0 +1,288 @@
+/**
+ * Wiki Compose orchestrator graph (#950) — wiring + interrupt tests.
+ *
+ * 受け入れ条件 #1 / #6 / 技術 #1:
+ * - `wikiComposeGraph` が P1 subgraph を組み込んでいる (channels 共有で表現)
+ * - Brief → research → outline → draft の happy path が動く
+ * - 各 interrupt 位置で halt し、resume で次フェーズに進む
+ *
+ * Mocks every LLM-backed node so the test pins the graph wiring rather than
+ * model quality. MemorySaver is used as a checkpointer so interrupts can
+ * resume on the same thread id.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  briefDialogue,
+  structureDialogue,
+  draftSections,
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+} = vi.hoisted(() => ({
+  briefDialogue: vi.fn(),
+  structureDialogue: vi.fn(),
+  draftSections: vi.fn(),
+  planQueries: vi.fn(),
+  webSearch: vi.fn(),
+  wikiSearch: vi.fn(),
+  fetchArticles: vi.fn(),
+  evaluateSufficiency: vi.fn(),
+  refineQueries: vi.fn(),
+  compileBatch: vi.fn(),
+}));
+
+// Real nodes preserved: humanReviewBrief, humanReviewOutline, completed,
+// humanReviewResearch (interrupts must be exercised, not mocked away).
+// Real interrupt/projection nodes are kept; only LLM-backed nodes are mocked.
+vi.mock("../../../../agents/graphs/wikiCompose/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/graphs/wikiCompose/nodes/index.js")
+  >("../../../../agents/graphs/wikiCompose/nodes/index.js");
+  return {
+    ...real,
+    briefDialogue,
+    structureDialogue,
+    draftSections,
+  };
+});
+
+vi.mock("../../../../agents/subgraphs/research/nodes/index.js", async () => {
+  const real = await vi.importActual<
+    typeof import("../../../../agents/subgraphs/research/nodes/index.js")
+  >("../../../../agents/subgraphs/research/nodes/index.js");
+  return {
+    ...real,
+    planQueries,
+    webSearch,
+    wikiSearch,
+    fetchArticles,
+    evaluateSufficiency,
+    refineQueries,
+    compileBatch,
+  };
+});
+
+import { GraphRunner } from "../../../../agents/runner/graphRunner.js";
+import { __resetRegistryForTests } from "../../../../agents/registry/graphRegistry.js";
+import {
+  WIKI_COMPOSE_GRAPH_ID,
+  registerWikiComposeGraph,
+} from "../../../../agents/graphs/wikiCompose/index.js";
+import type { GraphContext } from "../../../../agents/core/types/graphContext.js";
+import type { Database } from "../../../../types/index.js";
+import { MemorySaver } from "@langchain/langgraph";
+
+function fakeContext(threadId: string): GraphContext {
+  return {
+    threadId,
+    sessionId: threadId,
+    userId: "user-1",
+    pageId: "page-1",
+    graphId: WIKI_COMPOSE_GRAPH_ID,
+    backend: "zedi_managed",
+    tier: "free",
+    db: {} as Database,
+    feature: "wiki_compose:test",
+    userEmail: null,
+  };
+}
+
+function defaultMocks() {
+  briefDialogue.mockImplementation(async () => ({
+    briefQuestions: [
+      {
+        id: "q-1",
+        question: "What scope?",
+        options: [
+          { id: "opt-a", label: "broad" },
+          { id: "opt-b", label: "narrow" },
+        ],
+        required: false,
+      },
+    ],
+    pageSnapshot: { pageId: "page-1", title: "Hello", body: "", hasContent: false },
+    phase: "brief:await_user",
+  }));
+
+  planQueries.mockImplementation(async () => ({
+    queries: [{ id: "q1", query: "topic", channels: ["web"] }],
+    maxIterations: 3,
+    iteration: 0,
+    lastEvaluation: null,
+    exitReason: null,
+    phase: "research:plan",
+  }));
+  webSearch.mockImplementation(async () => ({
+    pendingSources: [{ id: "src:abc", kind: "web", title: "A", url: "https://a/" }],
+  }));
+  wikiSearch.mockImplementation(async () => ({ pendingSources: [] }));
+  fetchArticles.mockImplementation(async () => ({ pendingSources: [] }));
+  evaluateSufficiency.mockImplementation(async (state: { iteration: number }) => ({
+    lastEvaluation: { score: 0.9, rationale: "ok", missingAspects: [] },
+    iteration: state.iteration + 1,
+    phase: "research:evaluated",
+  }));
+  compileBatch.mockImplementation(
+    async (state: {
+      iteration: number;
+      queries: unknown[];
+      pendingSources: unknown[];
+      lastEvaluation: unknown;
+    }) => ({
+      batches: [
+        {
+          id: "batch-1",
+          iteration: state.iteration,
+          queries: state.queries,
+          sources: state.pendingSources,
+          evaluation: state.lastEvaluation,
+          createdAt: "2026-01-01T00:00:00.000Z",
+        },
+      ],
+      exitReason: "score_threshold",
+      phase: "research:compile",
+    }),
+  );
+
+  structureDialogue.mockImplementation(async () => ({
+    outlineProposal: [
+      { id: "sec-1", heading: "Overview", depth: 1, intent: "intro" },
+      { id: "sec-2", heading: "Details", depth: 1, intent: "deep dive" },
+    ],
+    phase: "structure:await_user",
+  }));
+
+  draftSections.mockImplementation(async () => ({
+    draftedSections: [
+      {
+        sectionId: "sec-1",
+        heading: "Overview",
+        body: "Body 1 [#1]",
+        citedSourceIds: ["src:abc"],
+        completedAt: "2026-01-01T00:00:01.000Z",
+      },
+      {
+        sectionId: "sec-2",
+        heading: "Details",
+        body: "Body 2",
+        citedSourceIds: [],
+        completedAt: "2026-01-01T00:00:02.000Z",
+      },
+    ],
+    phase: "draft:completed",
+  }));
+}
+
+describe("wikiComposeGraph — orchestrator wiring", () => {
+  beforeEach(() => {
+    __resetRegistryForTests();
+    registerWikiComposeGraph();
+    briefDialogue.mockReset();
+    structureDialogue.mockReset();
+    draftSections.mockReset();
+    planQueries.mockReset();
+    webSearch.mockReset();
+    wikiSearch.mockReset();
+    fetchArticles.mockReset();
+    evaluateSufficiency.mockReset();
+    refineQueries.mockReset();
+    compileBatch.mockReset();
+    defaultMocks();
+  });
+  afterEach(() => {
+    __resetRegistryForTests();
+  });
+
+  it("halts at the Brief interrupt on first run", async () => {
+    const runner = new GraphRunner();
+    const result = await runner.invoke(
+      {
+        graphId: WIKI_COMPOSE_GRAPH_ID,
+        context: fakeContext("thread-brief"),
+        checkpointer: new MemorySaver(),
+        recursionLimit: 120,
+      },
+      { kind: "input", value: { messages: [{ role: "user", content: "title: Hello" }] } },
+    );
+
+    expect(result.status).toBe("interrupted");
+    expect(briefDialogue).toHaveBeenCalledTimes(1);
+    // Should not have advanced past Brief before user resumes.
+    // Brief 確定前に research が走らないことを担保する。
+    expect(planQueries).not.toHaveBeenCalled();
+  });
+
+  it("advances to the research interrupt after Brief resume", async () => {
+    const checkpointer = new MemorySaver();
+    const runner = new GraphRunner();
+    const ctx = fakeContext("thread-research");
+
+    await runner.invoke(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { kind: "input", value: { messages: [{ role: "user", content: "title: Hello" }] } },
+    );
+
+    const resumed = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { answers: [], appendToExisting: false },
+    );
+
+    expect(resumed.status).toBe("interrupted");
+    expect(planQueries).toHaveBeenCalledTimes(1);
+    expect(compileBatch).toHaveBeenCalledTimes(1);
+    // Structure has not started yet — outline must wait for research approval.
+    // research 承認前に structure_dialogue が呼ばれないことを担保。
+    expect(structureDialogue).not.toHaveBeenCalled();
+  });
+
+  it("reaches Draft after research and outline resumes", async () => {
+    const checkpointer = new MemorySaver();
+    const runner = new GraphRunner();
+    const ctx = fakeContext("thread-draft");
+
+    // 1. Initial run halts at human_review_brief.
+    await runner.invoke(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { kind: "input", value: { messages: [{ role: "user", content: "title: Hello" }] } },
+    );
+    // 2. Brief resume → halts at human_review_research.
+    await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { answers: [], appendToExisting: false },
+    );
+    // 3. Research resume → halts at human_review_outline.
+    const outlineHalt = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      { approvedSourceIds: ["src:abc"] },
+    );
+    expect(outlineHalt.status).toBe("interrupted");
+    expect(structureDialogue).toHaveBeenCalledTimes(1);
+    expect(draftSections).not.toHaveBeenCalled();
+
+    // 4. Outline resume → runs Draft → completed.
+    const finalRun = await runner.resume(
+      { graphId: WIKI_COMPOSE_GRAPH_ID, context: ctx, checkpointer, recursionLimit: 120 },
+      {
+        sections: [
+          { id: "sec-1", heading: "Overview", depth: 1, intent: "intro" },
+          { id: "sec-2", heading: "Details", depth: 1, intent: "deep dive" },
+        ],
+      },
+    );
+    expect(finalRun.status).toBe("completed");
+    expect(draftSections).toHaveBeenCalledTimes(1);
+
+    const finalState = finalRun.output as {
+      completion?: { markdown?: string; sections?: unknown[] };
+    };
+    expect(finalState.completion).toBeTruthy();
+    expect(finalState.completion?.sections).toHaveLength(2);
+    expect(finalState.completion?.markdown).toMatch(/Overview/);
+    expect(finalState.completion?.markdown).toMatch(/Details/);
+  });
+});
diff --git a/server/api/src/__tests__/agents/runner/sseMapper.test.ts b/server/api/src/__tests__/agents/runner/sseMapper.test.ts
index ed6d6170..b8fdcac4 100644
--- a/server/api/src/__tests__/agents/runner/sseMapper.test.ts
+++ b/server/api/src/__tests__/agents/runner/sseMapper.test.ts
@@ -127,4 +127,48 @@ describe("mapLangGraphEvent", () => {
   it("returns an empty array for unrecognised events", () => {
     expect(mapLangGraphEvent({ event: "on_unknown_event" })).toEqual([]);
   });
+
+  it("maps on_custom_event compose_phase to a typed compose_phase event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_custom_event",
+      name: "compose_phase",
+      data: { phase: "structure", status: "entered" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      { type: "compose_phase", phase: "structure", status: "entered" },
+    ]);
+  });
+
+  it("drops compose_phase with an unknown phase value", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_custom_event",
+      name: "compose_phase",
+      data: { phase: "bogus", status: "entered" },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([]);
+  });
+
+  it("maps on_custom_event compose_section to a typed compose_section event", () => {
+    const ev: LangGraphRuntimeEvent = {
+      event: "on_custom_event",
+      name: "compose_section",
+      data: {
+        sectionId: "sec-1",
+        heading: "Overview",
+        status: "started",
+        index: 1,
+        total: 3,
+      },
+    };
+    expect(mapLangGraphEvent(ev)).toEqual([
+      {
+        type: "compose_section",
+        sectionId: "sec-1",
+        heading: "Overview",
+        status: "started",
+        index: 1,
+        total: 3,
+      },
+    ]);
+  });
 });
diff --git a/server/api/src/agents/core/types/sseEvents.ts b/server/api/src/agents/core/types/sseEvents.ts
index 8af30f3d..6983f45b 100644
--- a/server/api/src/agents/core/types/sseEvents.ts
+++ b/server/api/src/agents/core/types/sseEvents.ts
@@ -167,6 +167,45 @@ export interface SseResearchBatchEvent {
   exitReason: "score_threshold" | "max_iterations";
 }
 
+/**
+ * Wiki Compose 全体グラフ (#950) のフェーズ進捗通知。Brief → Research → Structure
+ * → Draft → Completed の遷移時に 1 件ずつ発火し、フロントの PhaseStepper の
+ * 進行表示に使う。`status` フィールドで「開始」「完了」を区別する。
+ *
+ * Orchestrator phase transition event. Emitted on enter / exit of each
+ * top-level phase so the frontend phase stepper can advance without
+ * inspecting state.
+ */
+export interface SseComposePhaseEvent {
+  type: "compose_phase";
+  /** Phase name (matches state.phase). */
+  phase: "brief" | "research" | "structure" | "draft" | "completed";
+  /** Lifecycle hint within the phase. */
+  status: "entered" | "completed";
+}
+
+/**
+ * Wiki Compose 全体グラフ (#950) のセクション ドラフト進捗通知。`draftSections`
+ * が 1 セクションを書き始める前 / 書き終わった後にそれぞれ 1 件発火する。
+ *
+ * Per-section draft progress event. Emitted by `draft_sections` at the start
+ * and end of each section so the editor pane can highlight the section that
+ * is currently streaming.
+ */
+export interface SseComposeSectionEvent {
+  type: "compose_section";
+  /** Matches `OutlineSection.id`. */
+  sectionId: string;
+  /** Final / running heading. */
+  heading: string;
+  /** Lifecycle: `started` before streaming, `completed` after the body is finalised. */
+  status: "started" | "completed";
+  /** 1-based index of this section within the outline. */
+  index: number;
+  /** Total number of sections in the outline. */
+  total: number;
+}
+
 /**
  * Wire-level SSE union.
  */
@@ -182,7 +221,9 @@ export type SseEvent =
   | SseErrorEvent
   | SseResearchIterationEvent
   | SseResearchEvaluationEvent
-  | SseResearchBatchEvent;
+  | SseResearchBatchEvent
+  | SseComposePhaseEvent
+  | SseComposeSectionEvent;
 
 /**
  * SSE event 名（`event:` 行に流す名前）。`SseEvent["type"]` と同値だが、
@@ -204,4 +245,6 @@ export const SSE_EVENT_NAMES = {
   researchIteration: "research_iteration",
   researchEvaluation: "research_evaluation",
   researchBatch: "research_batch",
+  composePhase: "compose_phase",
+  composeSection: "compose_section",
 } as const satisfies Record;
diff --git a/server/api/src/agents/graphs/wikiCompose/index.ts b/server/api/src/agents/graphs/wikiCompose/index.ts
new file mode 100644
index 00000000..108a0512
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/index.ts
@@ -0,0 +1,37 @@
+/**
+ * Wiki Compose orchestrator graph (#950) — public barrel.
+ *
+ * 全体グラフの外向け window。`app.ts` / `agents/index.ts` からこのファイル経由で
+ * `WIKI_COMPOSE_GRAPH_ID` と `registerWikiComposeGraph` を引く。直接ノードを
+ * import したいテストは `./nodes/index.js` を見る。
+ */
+export {
+  WIKI_COMPOSE_GRAPH_ID,
+  WIKI_COMPOSE_GRAPH_VERSION,
+  registerWikiComposeGraph,
+} from "./wikiComposeGraph.js";
+export {
+  WikiComposeState,
+  type WikiComposeStateType,
+  type WikiComposeStateUpdate,
+} from "./state.js";
+export type {
+  BriefAnswer,
+  BriefOption,
+  BriefQuestion,
+  BriefResult,
+  BriefResumeInput,
+  ApprovedOutline,
+  ComposeCompletion,
+  DraftedSection,
+  OutlineResumeInput,
+  OutlineSection,
+  PageSnapshot,
+  WikiComposeInterruptPayload,
+} from "./types.js";
+export {
+  briefResumeSchema,
+  type BriefResumeParsed,
+  outlineResumeSchema,
+  type OutlineResumeParsed,
+} from "./resumeSchemas.js";
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/briefDialogue.ts b/server/api/src/agents/graphs/wikiCompose/nodes/briefDialogue.ts
new file mode 100644
index 00000000..be4a5ec6
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/briefDialogue.ts
@@ -0,0 +1,150 @@
+/**
+ * `brief_dialogue` — Wiki Compose orchestrator entry node (#950).
+ *
+ * Brief フェーズの最初のノード。ページタイトル + 既存本文プレビューから、
+ * 0〜7 件の構造化質問を Orchestrator LLM に生成させる。`compose_phase` SSE を
+ * `entered` で発火し、生成後は `briefQuestions` を state に書き、`phase` を
+ * `brief:await_user` にして次の `human_review_brief` interrupt に進む。
+ *
+ * Brief never opens a free-form chat — it always emits the question cards
+ * that the frontend renders (the user fills them in and resumes). The node
+ * also loads the page snapshot exactly once at session start so downstream
+ * phases can read it without re-querying.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import { loadPageSnapshot } from "./shared/loadPageSnapshot.js";
+import { dispatchComposePhase } from "./shared/dispatch.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { BriefQuestion } from "../types.js";
+
+const ORCHESTRATOR_MODEL_ENV = "WIKI_COMPOSE_ORCHESTRATOR_MODEL_ID";
+const ORCHESTRATOR_MODEL_FALLBACK = "claude-3-5-haiku";
+
+function getOrchestratorModelId(): string {
+  return process.env[ORCHESTRATOR_MODEL_ENV]?.trim() || ORCHESTRATOR_MODEL_FALLBACK;
+}
+
+/**
+ * Schema for the LLM's structured output. The Orchestrator is told it MAY
+ * return zero questions when the title is unambiguous (e.g. a single specific
+ * proper noun with existing content). Hard cap at 7 to keep the UI scannable.
+ */
+export const briefQuestionsSchema = z.object({
+  questions: z
+    .array(
+      z.object({
+        question: z.string().min(1).max(200),
+        rationale: z.string().max(200).optional(),
+        options: z
+          .array(
+            z.object({
+              label: z.string().min(1).max(80),
+              hint: z.string().max(160).optional(),
+            }),
+          )
+          .max(6)
+          .default([]),
+        required: z.boolean().default(false),
+      }),
+    )
+    .min(0)
+    .max(7),
+});
+
+const SYSTEM_PROMPT =
+  "You are the orchestrator for Wiki Compose, an AI agent that helps a user " +
+  "co-author a wiki article. Given a page title (and optional existing body), " +
+  "decide what Brief questions (if any) you need to ask before research. " +
+  "Constraints:\n" +
+  "1. Output 0..7 questions. Prefer FEWER questions; only ask what is needed " +
+  "to disambiguate scope, audience, or depth.\n" +
+  "2. Each question MUST be answerable via option chips when reasonable " +
+  "(2..6 options). Free-text is always allowed on top, so don't add a " +
+  "trailing 'other' option.\n" +
+  "3. If the existing body is non-empty, you may include a question that " +
+  "asks whether to append or replace.\n" +
+  "4. Mark a question 'required: true' ONLY when leaving it unanswered would " +
+  "make the article unwritable. Most questions should be optional.\n" +
+  "Respond as JSON only.";
+
+function buildUserPrompt(title: string, body: string): string {
+  const parts: string[] = [`[Page title]`, title || "(no title yet)"];
+  if (body.trim()) {
+    parts.push(
+      "",
+      "[Existing body excerpt — first ~600 chars]",
+      body.slice(0, 600),
+      body.length > 600 ? `\n(…truncated; total ${body.length} chars)` : "",
+    );
+  } else {
+    parts.push("", "(Page body is empty.)");
+  }
+  return parts.join("\n");
+}
+
+/**
+ * `brief_dialogue` node — generates the Brief question cards and stamps the
+ * `pageSnapshot` into state.
+ */
+export async function briefDialogue(
+  state: WikiComposeStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const ctx = getGraphContext(config);
+
+  await dispatchComposePhase({ phase: "brief", status: "entered" }, config);
+
+  // Load the snapshot once. Subsequent phases read from state, never the DB.
+  // セッション開始時に 1 度だけ読み、以後は state を参照する。
+  const snapshot = state.pageSnapshot ?? (await loadPageSnapshot(ctx.db, ctx.pageId));
+
+  const model = await createZediChatModel({
+    modelId: getOrchestratorModelId(),
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:brief`,
+    backend: ctx.backend,
+    temperature: 0.3,
+    maxTokens: 1024,
+  });
+  const structured = model.withStructuredOutput(briefQuestionsSchema, { name: "brief_dialogue" });
+
+  // `structured.invoke` returns the zod input type (pre-default), so we
+  // accept it as-is and apply fallbacks at the projection step below.
+  let raw: z.input;
+  try {
+    raw = await structured.invoke([
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: buildUserPrompt(snapshot.title, snapshot.body) },
+    ]);
+  } catch {
+    // Defensive fallback: if the LLM call fails, emit an empty Brief so the
+    // user can still proceed straight to research. The orchestrator must not
+    // become unstartable just because of a transient model error.
+    // LLM 失敗時は Brief 0 件で先へ進ませる安全策。
+    raw = { questions: [] };
+  }
+
+  const briefQuestions: BriefQuestion[] = raw.questions.map((q) => ({
+    id: randomUUID(),
+    question: q.question,
+    rationale: q.rationale,
+    options: (q.options ?? []).map((o) => ({
+      id: randomUUID(),
+      label: o.label,
+      hint: o.hint,
+    })),
+    required: Boolean(q.required),
+  }));
+
+  return {
+    pageSnapshot: snapshot,
+    briefQuestions,
+    phase: "brief:await_user",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/completed.ts b/server/api/src/agents/graphs/wikiCompose/nodes/completed.ts
new file mode 100644
index 00000000..ab535017
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/completed.ts
@@ -0,0 +1,66 @@
+/**
+ * `completed` — Wiki Compose terminal node (#950).
+ *
+ * Draft フェーズ後の最終ノード。`draftedSections` を `approvedOutline` の順に
+ * 並べ替えて Markdown を組み立て、`completion` に書き込む。citation source は
+ * `approvedResearch` から実際に引用された分だけ抽出する。`compose_phase` SSE
+ * を `completed` で発火し、ストリームを終了する。
+ *
+ * Pure projection node. Sequences `draftedSections` by `approvedOutline`
+ * order, concatenates them with `## heading` lines, and collates the cited
+ * sources for the final compose output. No LLM call.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { dispatchComposePhase } from "./shared/dispatch.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { ComposeCompletion, DraftedSection, Source } from "../types.js";
+
+/** `completed` node — final projection. */
+export async function completed(
+  state: WikiComposeStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const outline = state.approvedOutline?.sections ?? [];
+  const draftById = new Map();
+  for (const d of state.draftedSections) draftById.set(d.sectionId, d);
+
+  // Walk the outline so the final order matches the user's approved layout
+  // even if `draftedSections` was filled in a different order (mid-flight
+  // re-draft, etc.).
+  // ユーザー承認済みアウトラインの順に並べる。
+  const ordered: DraftedSection[] = [];
+  for (const section of outline) {
+    const drafted = draftById.get(section.id);
+    if (drafted) ordered.push(drafted);
+  }
+
+  const lines: string[] = [];
+  for (const section of outline) {
+    const drafted = draftById.get(section.id);
+    if (!drafted) continue;
+    const prefix = "#".repeat(Math.min(3, Math.max(2, section.depth + 1)));
+    lines.push(`${prefix} ${section.heading}`);
+    lines.push("");
+    lines.push(drafted.body);
+    lines.push("");
+  }
+  const markdown = lines.join("\n").trim() + "\n";
+
+  const citedIds = new Set();
+  for (const d of ordered) for (const id of d.citedSourceIds) citedIds.add(id);
+  const citedSources: Source[] = state.approvedResearch.filter((s) => citedIds.has(s.id));
+
+  const completion: ComposeCompletion = {
+    markdown,
+    sections: ordered,
+    citedSources,
+    completedAt: new Date().toISOString(),
+  };
+
+  await dispatchComposePhase({ phase: "completed", status: "entered" }, config);
+
+  return {
+    completion,
+    phase: "completed",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/draftSections.ts b/server/api/src/agents/graphs/wikiCompose/nodes/draftSections.ts
new file mode 100644
index 00000000..52e1976d
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/draftSections.ts
@@ -0,0 +1,239 @@
+/**
+ * `draft_sections` — Wiki Compose Draft phase node (#950).
+ *
+ * 承認済みアウトラインの各セクションを LLM ストリーミングで本文化する。
+ * セクションごとに `compose_section { status: "started" }` を発火し、LLM の
+ * `streamEvents` 経由でトークンが SSE `token` イベントとして流れる
+ * （`sseMapper.mapChatModelStream` が拾う）。1 セクション完了ごとに
+ * `compose_section { status: "completed" }` を出し、`draftedSections` に追記する。
+ *
+ * Sequential per-section streaming: each section is streamed as a single
+ * `stream()` call so the SSE wire produces a `token` event per chunk under
+ * the `draft_sections` node label, which the frontend uses to incrementally
+ * paint into the EditorPane.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import { dispatchComposePhase, dispatchComposeSection } from "./shared/dispatch.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { DraftedSection, OutlineSection, Source } from "../types.js";
+
+const DRAFT_MODEL_ENV = "WIKI_COMPOSE_DRAFT_MODEL_ID";
+const DRAFT_MODEL_FALLBACK = "claude-3-5-sonnet";
+
+function getDraftModelId(): string {
+  return process.env[DRAFT_MODEL_ENV]?.trim() || DRAFT_MODEL_FALLBACK;
+}
+
+const SECTION_SYSTEM_PROMPT =
+  "You are a co-author writing one section of a wiki article. Constraints:\n" +
+  "1. Output Markdown body ONLY — do NOT repeat the heading line.\n" +
+  "2. Stay focused on the section's intent. Do not introduce content that " +
+  "belongs to a sibling section.\n" +
+  "3. Cite sources inline as `[#N]` referring to the numbered approved " +
+  "research list. Only cite sources that genuinely support the claim.\n" +
+  "4. Aim for ~250–500 words. Use sub-headings only when depth=2 is " +
+  "specified for sub-sections within the same draft pass.\n" +
+  "5. Plain Markdown; no HTML, no YAML frontmatter.";
+
+function numberedSourceList(sources: Source[], allowedIds?: string[]): string[] {
+  const allow = allowedIds && allowedIds.length > 0 ? new Set(allowedIds) : null;
+  return sources
+    .filter((s) => !allow || allow.has(s.id))
+    .map((s, i) => {
+      const tag = s.kind.toUpperCase();
+      const url = s.finalUrl ?? s.url ?? "";
+      const blurb = s.excerpt ?? s.snippet ?? "";
+      const tail = blurb ? `\n   ${blurb.slice(0, 240)}` : "";
+      return `[#${i + 1}] (${tag}) ${s.title}${url ? ` — ${url}` : ""}${tail}`;
+    });
+}
+
+function buildSectionPrompt(args: {
+  pageTitle: string;
+  section: OutlineSection;
+  outline: OutlineSection[];
+  briefSummary: string;
+  sources: Source[];
+}): string {
+  const { pageTitle, section, outline, briefSummary, sources } = args;
+  const outlineList = outline.map((s) => {
+    const indent = "  ".repeat(Math.max(0, s.depth - 1));
+    const marker = s.id === section.id ? "→" : "•";
+    return `${indent}${marker} ${s.heading} — ${s.intent}`;
+  });
+  const sourceLines = numberedSourceList(sources, section.sourceIds);
+  return [
+    `[Page title]`,
+    pageTitle,
+    "",
+    "[Brief summary]",
+    briefSummary,
+    "",
+    "[Full outline — '→' marks the section you are writing]",
+    ...outlineList,
+    "",
+    "[Section to write]",
+    `heading: ${section.heading}`,
+    `depth: ${section.depth}`,
+    `intent: ${section.intent}`,
+    "",
+    `[Approved sources (${sourceLines.length})]`,
+    ...(sourceLines.length > 0 ? sourceLines : ["(no sources — write conservatively)"]),
+  ].join("\n");
+}
+
+/**
+ * Sum the chunks of a streamed chat result into a single string. We rely on
+ * the LangGraph runtime to also emit each chunk as an `on_chat_model_stream`
+ * event so the SSE mapper produces `token` events the frontend reads.
+ *
+ * ストリーミングの最終結果を 1 本の文字列にまとめる。途中チャンクは
+ * runtime が `on_chat_model_stream` event として吐くので、SSE には別経路で
+ * `token` event が流れる。
+ */
+function chunkContent(chunk: unknown): string {
+  if (!chunk || typeof chunk !== "object") return "";
+  const content = (chunk as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        if (
+          part &&
+          typeof part === "object" &&
+          typeof (part as { text?: unknown }).text === "string"
+        ) {
+          return (part as { text: string }).text;
+        }
+        return "";
+      })
+      .join("");
+  }
+  return "";
+}
+
+/** `draft_sections` node — sequential per-section LLM streaming. */
+export async function draftSections(
+  state: WikiComposeStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const ctx = getGraphContext(config);
+
+  await dispatchComposePhase({ phase: "draft", status: "entered" }, config);
+
+  const outline = state.approvedOutline?.sections ?? [];
+  if (outline.length === 0) {
+    // Defensive: humanReviewOutline already rejects empty arrays, but if we
+    // somehow arrive here with nothing to write, skip Draft cleanly.
+    // 通常は到達不能だが防御。空アウトラインなら Draft をスキップ。
+    return { draftedSections: [], phase: "draft:completed" };
+  }
+
+  const model = await createZediChatModel({
+    modelId: getDraftModelId(),
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:draft`,
+    backend: ctx.backend,
+    temperature: 0.6,
+    maxTokens: 2048,
+  });
+
+  const pageTitle = state.pageSnapshot?.title ?? "(untitled)";
+  const briefSummary = state.brief?.summary ?? "(no brief)";
+  const drafted: DraftedSection[] = [];
+
+  for (let i = 0; i < outline.length; i++) {
+    const section = outline[i] as OutlineSection;
+    await dispatchComposeSection(
+      {
+        sectionId: section.id,
+        heading: section.heading,
+        status: "started",
+        index: i + 1,
+        total: outline.length,
+      },
+      config,
+    );
+
+    let body = "";
+    try {
+      const stream = await model.stream([
+        { role: "system", content: SECTION_SYSTEM_PROMPT },
+        {
+          role: "user",
+          content: buildSectionPrompt({
+            pageTitle,
+            section,
+            outline,
+            briefSummary,
+            sources: state.approvedResearch,
+          }),
+        },
+      ]);
+      for await (const chunk of stream) {
+        body += chunkContent(chunk);
+      }
+    } catch (err) {
+      // Per-section failure must not abort the whole Draft. Surface the
+      // failure as an inline note inside the section body so the user sees
+      // what happened without losing earlier sections.
+      // セクション 1 件の失敗で Draft 全体を止めない。エラーは本文に追記。
+      const message = err instanceof Error ? err.message : String(err);
+      body = body || `*(Section draft failed: ${message})*`;
+    }
+
+    const citedIds = collectCitedSourceIds(body, state.approvedResearch, section.sourceIds);
+    drafted.push({
+      sectionId: section.id,
+      heading: section.heading,
+      body: body.trim(),
+      citedSourceIds: citedIds,
+      completedAt: new Date().toISOString(),
+    });
+
+    await dispatchComposeSection(
+      {
+        sectionId: section.id,
+        heading: section.heading,
+        status: "completed",
+        index: i + 1,
+        total: outline.length,
+      },
+      config,
+    );
+  }
+
+  return {
+    draftedSections: drafted,
+    phase: "draft:completed",
+  };
+}
+
+/**
+ * Best-effort extraction of cited source ids from `[#N]` markers in the body.
+ * Maps each `[#N]` back to the corresponding source by 1-based index over the
+ * allowed-source subset.
+ *
+ * 本文中の `[#N]` 形式の引用マーカーから citedSourceIds を抽出する。
+ */
+function collectCitedSourceIds(
+  body: string,
+  sources: Source[],
+  allowedIds: string[] | undefined,
+): string[] {
+  const allow = allowedIds && allowedIds.length > 0 ? new Set(allowedIds) : null;
+  const candidates = sources.filter((s) => !allow || allow.has(s.id));
+  const matches = new Set();
+  for (const m of body.matchAll(/\[#(\d+)\]/g)) {
+    const n = Number(m[1]);
+    if (!Number.isFinite(n) || n < 1 || n > candidates.length) continue;
+    const candidate = candidates[n - 1];
+    if (candidate) matches.add(candidate.id);
+  }
+  return Array.from(matches);
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewBrief.ts b/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewBrief.ts
new file mode 100644
index 00000000..cde00cfe
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewBrief.ts
@@ -0,0 +1,91 @@
+/**
+ * `human_review_brief` — Wiki Compose Brief interrupt node (#950).
+ *
+ * Brief 質問群を `interrupt(value)` でユーザーに渡し、`PATCH .../resume` の
+ * 結果を `briefResumeSchema` で検証して `brief` を state に確定する。
+ * 既存本文ありで「追記」を選んだ場合は `appendToExisting=true` が立ち、Draft
+ * フェーズがそれを読んで挙動を切り替える。`researchMaxIterations` (1..5) が
+ * 指定されていれば、後段の Research subgraph に渡るようミラーする。
+ *
+ * Halts the graph at the Brief interrupt and projects the user's answers into
+ * `state.brief`. The resume payload's `researchMaxIterations` (when present)
+ * is mirrored to `state.researchMaxIterations` so the research subgraph node
+ * picks it up via its own state slot when invoked.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { interrupt } from "@langchain/langgraph";
+import { briefResumeSchema } from "../resumeSchemas.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type {
+  BriefAnswer,
+  BriefResult,
+  PageSnapshot,
+  WikiComposeInterruptPayload,
+} from "../types.js";
+
+const EMPTY_SNAPSHOT: PageSnapshot = { pageId: "", title: "", body: "", hasContent: false };
+
+/**
+ * Build the natural-language Brief summary that downstream nodes embed in
+ * their prompts. Keeps the structure stable so prompt-snapshot tests don't
+ * churn on LLM upgrades.
+ *
+ * Brief 確定回答を Markdown で要約する。後段プロンプトに渡す書式を 1 箇所に集約する。
+ */
+function summariseBrief(answers: BriefAnswer[], questions: Map): string {
+  if (answers.length === 0) return "(no brief provided)";
+  const lines: string[] = [];
+  for (const a of answers) {
+    const q = questions.get(a.questionId) ?? "(unknown question)";
+    const parts: string[] = [];
+    if (a.selectedOptionIds.length > 0) parts.push(`selected=${a.selectedOptionIds.join(", ")}`);
+    if (a.freeText && a.freeText.trim()) parts.push(`note=${a.freeText.trim()}`);
+    lines.push(`- ${q} → ${parts.join(" | ") || "(no answer)"}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * `human_review_brief` node — interrupt + resume projection.
+ */
+export async function humanReviewBrief(
+  state: WikiComposeStateType,
+  _config: LangGraphRunnableConfig,
+): Promise {
+  const payload: WikiComposeInterruptPayload = {
+    kind: "human_review_brief",
+    questions: state.briefQuestions,
+    pageSnapshot: state.pageSnapshot ?? EMPTY_SNAPSHOT,
+  };
+  const resumeValue: unknown = interrupt(payload);
+  const parsed = briefResumeSchema.parse(resumeValue);
+
+  // Index questions by id so we can produce a stable, readable summary.
+  // 質問テキストを id → text で引けるよう、ループの外で 1 度だけ Map 化する。
+  const questionMap = new Map();
+  for (const q of state.briefQuestions) questionMap.set(q.id, q.question);
+
+  const answers: BriefAnswer[] = parsed.answers.map((a) => ({
+    questionId: a.questionId,
+    selectedOptionIds: a.selectedOptionIds,
+    ...(a.freeText !== undefined ? { freeText: a.freeText } : {}),
+  }));
+
+  const brief: BriefResult = {
+    answers,
+    summary: summariseBrief(answers, questionMap),
+    appendToExisting: Boolean(parsed.appendToExisting),
+  };
+
+  const update: WikiComposeStateUpdate = {
+    brief,
+    phase: "brief:completed",
+  };
+  if (parsed.researchMaxIterations !== undefined) {
+    // Mirror onto the canonical research subgraph channel name so the
+    // composed research node picks it up via shared state.
+    // research subgraph と共有する `maxIterations` チャネルに反映する。
+    update.maxIterations = parsed.researchMaxIterations;
+  }
+  return update;
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewOutline.ts b/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewOutline.ts
new file mode 100644
index 00000000..919d921c
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/humanReviewOutline.ts
@@ -0,0 +1,46 @@
+/**
+ * `human_review_outline` — Wiki Compose Structure interrupt node (#950).
+ *
+ * Orchestrator が提案したアウトラインを `interrupt(value)` でユーザーに渡し、
+ * `outlineResumeSchema` で検証して `approvedOutline` を state に確定する。
+ * ユーザーは並び替え・タイトル変更・depth 変更・サブセクション削除が可能
+ * （フロントの outline editor で全部行う）。承認後は Draft フェーズへ。
+ *
+ * Halts at the outline interrupt and projects the user-edited outline back
+ * into state. Validation throws on empty outlines so Draft cannot be entered
+ * with nothing to write.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { interrupt } from "@langchain/langgraph";
+import { outlineResumeSchema } from "../resumeSchemas.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { ApprovedOutline, WikiComposeInterruptPayload } from "../types.js";
+
+/** `human_review_outline` node — interrupt + resume projection. */
+export async function humanReviewOutline(
+  state: WikiComposeStateType,
+  _config: LangGraphRunnableConfig,
+): Promise {
+  const payload: WikiComposeInterruptPayload = {
+    kind: "human_review_outline",
+    outline: state.outlineProposal,
+    approvedSources: state.approvedResearch,
+  };
+  const resumeValue: unknown = interrupt(payload);
+  const parsed = outlineResumeSchema.parse(resumeValue);
+
+  const approvedOutline: ApprovedOutline = {
+    sections: parsed.sections.map((s) => ({
+      id: s.id,
+      heading: s.heading,
+      depth: s.depth,
+      intent: s.intent,
+      ...(s.sourceIds !== undefined ? { sourceIds: s.sourceIds } : {}),
+    })),
+  };
+
+  return {
+    approvedOutline,
+    phase: "structure:completed",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/index.ts b/server/api/src/agents/graphs/wikiCompose/nodes/index.ts
new file mode 100644
index 00000000..55ca4185
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/index.ts
@@ -0,0 +1,12 @@
+/**
+ * Barrel for Wiki Compose orchestrator graph nodes (#950).
+ *
+ * `wikiComposeGraph.ts` から個別ファイルを import せずに済むようまとめる。
+ * テストでも単一の mock point として使う。
+ */
+export { briefDialogue } from "./briefDialogue.js";
+export { humanReviewBrief } from "./humanReviewBrief.js";
+export { structureDialogue } from "./structureDialogue.js";
+export { humanReviewOutline } from "./humanReviewOutline.js";
+export { draftSections } from "./draftSections.js";
+export { completed } from "./completed.js";
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/shared/dispatch.ts b/server/api/src/agents/graphs/wikiCompose/nodes/shared/dispatch.ts
new file mode 100644
index 00000000..9ee4f584
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/shared/dispatch.ts
@@ -0,0 +1,41 @@
+/**
+ * Typed wrappers over `dispatchCustomEvent` for the Wiki Compose orchestrator
+ * graph (#950).
+ *
+ * `dispatchCustomEvent` を経由して `compose_phase` / `compose_section` の
+ * custom event を発火する薄いラッパ。`sseMapper.mapCustomEvent` がペイロード
+ * shape を検証するため、ここでは型付きで dispatch するだけで良い。
+ */
+import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+
+/** Payload shape for `compose_phase` custom events. */
+export interface ComposePhasePayload {
+  phase: "brief" | "research" | "structure" | "draft" | "completed";
+  status: "entered" | "completed";
+}
+
+/** Payload shape for `compose_section` custom events. */
+export interface ComposeSectionPayload {
+  sectionId: string;
+  heading: string;
+  status: "started" | "completed";
+  index: number;
+  total: number;
+}
+
+/** Dispatch a `compose_phase` SSE custom event. */
+export async function dispatchComposePhase(
+  payload: ComposePhasePayload,
+  config: LangGraphRunnableConfig,
+): Promise {
+  await dispatchCustomEvent("compose_phase", payload, config);
+}
+
+/** Dispatch a `compose_section` SSE custom event. */
+export async function dispatchComposeSection(
+  payload: ComposeSectionPayload,
+  config: LangGraphRunnableConfig,
+): Promise {
+  await dispatchCustomEvent("compose_section", payload, config);
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/shared/loadPageSnapshot.ts b/server/api/src/agents/graphs/wikiCompose/nodes/shared/loadPageSnapshot.ts
new file mode 100644
index 00000000..2cb365f2
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/shared/loadPageSnapshot.ts
@@ -0,0 +1,54 @@
+/**
+ * Loads a {@link PageSnapshot} for the Wiki Compose orchestrator graph (#950).
+ *
+ * `briefDialogue` ノードが session 開始時に 1 度だけ呼ぶ。`pages` / `page_versions`
+ * テーブルから現在のタイトル・本文を取得し、Brief 質問生成 / 追記モード判定に
+ * 利用できる軽量レコードを返す。失敗時は空タイトル + 空本文の安全な fallback
+ * を返す（Brief 自体は無タイトルでも 0 件質問で進めるよう設計してある）。
+ *
+ * Reads the target page's current title + body so Brief can suggest informed
+ * questions and Draft can know whether to append vs replace. Falls back to a
+ * zero-content snapshot when the page row cannot be loaded (rare; the route
+ * layer already verified view access before invoking the graph).
+ */
+import { eq } from "drizzle-orm";
+import { pages } from "../../../../../schema/pages.js";
+import type { Database } from "../../../../../types/index.js";
+import type { PageSnapshot } from "../../types.js";
+
+/**
+ * Fetch a page snapshot. The function is intentionally narrow — it only reads
+ * the fields the orchestrator nodes need, so it doesn't drag the full page
+ * accessor service into the agent runtime.
+ */
+export async function loadPageSnapshot(db: Database, pageId: string): Promise {
+  try {
+    const [row] = await db
+      .select({ id: pages.id, title: pages.title, contentPreview: pages.contentPreview })
+      .from(pages)
+      .where(eq(pages.id, pageId))
+      .limit(1);
+    if (!row) return emptySnapshot(pageId);
+    // `pages.content_preview` holds the latest persisted markdown-like preview
+    // of the body (the live document lives in Hocuspocus). For the orchestrator
+    // it's enough to know whether content exists and surface a short excerpt;
+    // we don't need the full Yjs binary.
+    // `pages.content_preview` は本文のプレビュー文字列を保持している（実体は
+    // Hocuspocus）。Brief / Draft の判断には十分なので、ここで読む。
+    const body = typeof row.contentPreview === "string" ? row.contentPreview : "";
+    return {
+      pageId: row.id,
+      title: row.title ?? "",
+      body,
+      hasContent: body.trim().length > 0,
+    };
+  } catch {
+    // Defence in depth: a transient DB error must not crash the whole graph.
+    // The Brief node tolerates an empty snapshot (it just asks broader questions).
+    return emptySnapshot(pageId);
+  }
+}
+
+function emptySnapshot(pageId: string): PageSnapshot {
+  return { pageId, title: "", body: "", hasContent: false };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/nodes/structureDialogue.ts b/server/api/src/agents/graphs/wikiCompose/nodes/structureDialogue.ts
new file mode 100644
index 00000000..b7f5947b
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/nodes/structureDialogue.ts
@@ -0,0 +1,135 @@
+/**
+ * `structure_dialogue` — Wiki Compose Structure phase node (#950).
+ *
+ * Brief 確定回答と採用調査ソースを材料に、3〜10 セクションのアウトライン
+ * 案を Orchestrator LLM に生成させる。Draft フェーズが書きやすい粒度
+ * （= 各セクションが独立して 1 LLM 呼びぶんに収まる）を狙う。生成後は
+ * `outlineProposal` に置き、`compose_phase: { phase: "structure", status: "entered" }`
+ * を発火して `human_review_outline` interrupt に進む。
+ *
+ * Builds an outline proposal that the user can edit before Draft. The
+ * prompt is intentionally narrow on shape (heading + intent) so the
+ * frontend's drag-and-drop editor has stable rows to work with.
+ */
+import type { LangGraphRunnableConfig } from "@langchain/langgraph";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { createZediChatModel } from "../../../core/llm/modelFactory.js";
+import { getGraphContext } from "../../../subgraphs/research/nodes/shared/getGraphContext.js";
+import { dispatchComposePhase } from "./shared/dispatch.js";
+import type { WikiComposeStateType, WikiComposeStateUpdate } from "../state.js";
+import type { OutlineSection } from "../types.js";
+
+const ORCHESTRATOR_MODEL_ENV = "WIKI_COMPOSE_ORCHESTRATOR_MODEL_ID";
+const ORCHESTRATOR_MODEL_FALLBACK = "claude-3-5-haiku";
+
+function getOrchestratorModelId(): string {
+  return process.env[ORCHESTRATOR_MODEL_ENV]?.trim() || ORCHESTRATOR_MODEL_FALLBACK;
+}
+
+/**
+ * Structured output schema. 3..10 sections, depth 1..3, each with a short
+ * intent so the user can spot redundant or off-topic items at a glance.
+ */
+export const outlineProposalSchema = z.object({
+  sections: z
+    .array(
+      z.object({
+        heading: z.string().min(1).max(120),
+        depth: z.number().int().min(1).max(3).default(1),
+        intent: z.string().min(1).max(280),
+      }),
+    )
+    .min(3)
+    .max(10),
+});
+
+const SYSTEM_PROMPT =
+  "You are the orchestrator for Wiki Compose. Produce a section outline for " +
+  "the wiki page based on the Brief answers and the approved research " +
+  "sources. Constraints:\n" +
+  "1. 3..10 sections. Each MUST be writable in a single ~600-word pass.\n" +
+  "2. Use depth=1 for top-level h2 sections, depth=2 for h3 sub-sections.\n" +
+  "3. Each section MUST include a one-sentence `intent` describing what to " +
+  "cover. The user reads this to decide whether to keep / reorder / drop.\n" +
+  "4. Do not include 'Introduction' or 'Conclusion' boilerplate unless the " +
+  "topic genuinely benefits from one.\n" +
+  "Output JSON only.";
+
+function buildUserPrompt(state: WikiComposeStateType): string {
+  const title = state.pageSnapshot?.title ?? "(untitled)";
+  const briefSummary = state.brief?.summary ?? "(no brief provided)";
+  const sources = state.approvedResearch.slice(0, 20).map((s, i) => {
+    const kind = s.kind.toUpperCase();
+    return `[${i + 1}] (${kind}) ${s.title}`;
+  });
+  const sourceBlock = sources.length > 0 ? sources.join("\n") : "(no approved research sources)";
+  return [
+    `[Page title]`,
+    title,
+    "",
+    "[Brief summary]",
+    briefSummary,
+    "",
+    `[Approved research sources: ${state.approvedResearch.length}]`,
+    sourceBlock,
+  ].join("\n");
+}
+
+/** `structure_dialogue` node — proposes the outline. */
+export async function structureDialogue(
+  state: WikiComposeStateType,
+  config: LangGraphRunnableConfig,
+): Promise {
+  const ctx = getGraphContext(config);
+
+  await dispatchComposePhase({ phase: "structure", status: "entered" }, config);
+
+  const model = await createZediChatModel({
+    modelId: getOrchestratorModelId(),
+    userId: ctx.userId,
+    tier: ctx.tier,
+    db: ctx.db,
+    feature: `${ctx.feature}:structure`,
+    backend: ctx.backend,
+    temperature: 0.4,
+    maxTokens: 2048,
+  });
+  const structured = model.withStructuredOutput(outlineProposalSchema, {
+    name: "structure_dialogue",
+  });
+
+  // `structured.invoke` returns the zod input type (pre-default); we apply
+  // fallbacks (`depth ?? 1`) at the projection step below.
+  let raw: z.input;
+  try {
+    raw = await structured.invoke([
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: buildUserPrompt(state) },
+    ]);
+  } catch {
+    // Defensive fallback: emit a minimal 3-section outline so the user can
+    // edit-rather-than-blank-out when the LLM fails (rare). Heading text
+    // intentionally generic so the user is prompted to rename.
+    // LLM 失敗時は 3 セクションの仮アウトラインを返してフローを止めない。
+    raw = {
+      sections: [
+        { heading: "Overview", depth: 1, intent: "Brief introduction to the topic." },
+        { heading: "Key points", depth: 1, intent: "Main facts and context." },
+        { heading: "References", depth: 1, intent: "Sources and further reading." },
+      ],
+    };
+  }
+
+  const outline: OutlineSection[] = raw.sections.map((s) => ({
+    id: randomUUID(),
+    heading: s.heading,
+    depth: s.depth ?? 1,
+    intent: s.intent,
+  }));
+
+  return {
+    outlineProposal: outline,
+    phase: "structure:await_user",
+  };
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/resumeSchemas.ts b/server/api/src/agents/graphs/wikiCompose/resumeSchemas.ts
new file mode 100644
index 00000000..8ac9fe12
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/resumeSchemas.ts
@@ -0,0 +1,66 @@
+/**
+ * Resume payload validators for the Wiki Compose orchestrator graph (#950).
+ *
+ * 各 interrupt 点で `PATCH /api/pages/:pageId/compose-sessions/:id/resume` が
+ * 受け取る `body.resume` の shape を zod で検証する。Brief / Outline それぞれ
+ * 専用のスキーマを持つ（Research は subgraph 側の `researchResumeSchema` を流用）。
+ *
+ * Validates the resume payload submitted via the resume endpoint at each
+ * orchestrator interrupt point. The route layer hands `body.resume` to the
+ * graph and these schemas catch malformed payloads before they pollute state.
+ */
+import { z } from "zod";
+
+/**
+ * Resume payload for `human_review_brief`.
+ *
+ * - `answers` — 必須。空配列でも可（Brief をスキップしたケース）。
+ * - `appendToExisting` — 本文ありページで「追記」を選んだ場合 true。
+ * - `researchMaxIterations` — Brief 内で 1..5 にユーザーが調整した場合のみ。
+ *
+ * Validates the resume payload at the Brief interrupt. `answers` is required
+ * even when empty (the user may explicitly skip Brief by submitting an empty
+ * array). Default for `appendToExisting` is `false` (replace-mode is the
+ * historical Wiki Compose behaviour); `researchMaxIterations` is clamped to
+ * 1..5 by the schema so the graph never sees an out-of-range value.
+ */
+export const briefResumeSchema = z.object({
+  answers: z
+    .array(
+      z.object({
+        questionId: z.string().min(1),
+        selectedOptionIds: z.array(z.string().min(1)).default([]),
+        freeText: z.string().optional(),
+      }),
+    )
+    .default([]),
+  appendToExisting: z.boolean().optional().default(false),
+  researchMaxIterations: z.number().int().min(1).max(5).optional(),
+});
+
+export type BriefResumeParsed = z.infer;
+
+/**
+ * Resume payload for `human_review_outline`.
+ *
+ * - `sections` — 確定アウトライン。空配列は許容しない（最低 1 セクションは必要）。
+ *
+ * Validates the resume payload at the outline interrupt. The user must
+ * approve at least one section — an empty outline is rejected so Draft does
+ * not try to render an article with no sections.
+ */
+export const outlineResumeSchema = z.object({
+  sections: z
+    .array(
+      z.object({
+        id: z.string().min(1),
+        heading: z.string().min(1),
+        depth: z.number().int().min(1).max(3),
+        intent: z.string().default(""),
+        sourceIds: z.array(z.string().min(1)).optional(),
+      }),
+    )
+    .min(1),
+});
+
+export type OutlineResumeParsed = z.infer;
diff --git a/server/api/src/agents/graphs/wikiCompose/state.ts b/server/api/src/agents/graphs/wikiCompose/state.ts
new file mode 100644
index 00000000..03e793d6
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/state.ts
@@ -0,0 +1,195 @@
+/**
+ * `WikiComposeState` — orchestrator-level LangGraph state for Wiki Compose
+ * P2 (#950).
+ *
+ * Wiki Compose 全体グラフの state。`BaseState` (messages / phase / pageId /
+ * userId) を継承しつつ、`ResearchLoopState` の channel 群 (`iteration` /
+ * `pendingSources` / `approvedResearch` 等) を superset として保持することで、
+ * 既存の `researchLoopSubgraph` をそのまま **subgraph as node** として組み込み、
+ * state を自動的に共有させる。Brief / Structure / Draft の各フェーズ専用の
+ * フィールド (`briefQuestions`, `brief`, `outlineProposal`, `approvedOutline`,
+ * `draftedSections`, `completion`) を追加で持つ。
+ *
+ * Extends both `BaseState` and the research subgraph's channels so the compiled
+ * research graph composes as a regular node (LangGraph maps state automatically
+ * when channel names + reducers match). Each phase writes only to its own
+ * slice; reducers are last-write-wins for scalars and id-keyed merge for arrays.
+ *
+ * Issue: otomatty/zedi#950
+ */
+import { Annotation } from "@langchain/langgraph";
+import { BaseState } from "../../core/state/baseState.js";
+import type {
+  AdditionalResearchRequest,
+  Evaluation,
+  ExitReason,
+  PlannedQuery,
+  ResearchBatch,
+  Source,
+} from "../../subgraphs/research/types.js";
+import type {
+  ApprovedOutline,
+  BriefQuestion,
+  BriefResult,
+  ComposeCompletion,
+  DraftedSection,
+  OutlineSection,
+  PageSnapshot,
+} from "./types.js";
+
+/**
+ * `pendingSources` 用 reducer。id 単位で dedup し、後勝ちで上書きする。
+ * Source merge by id with last-write-wins; mirrors the research subgraph.
+ */
+function mergeSourcesById(prev: Source[], next: Source[] | undefined): Source[] {
+  if (!next || next.length === 0) return prev;
+  const order: string[] = [];
+  const map = new Map();
+  for (const s of prev) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  for (const s of next) {
+    if (!map.has(s.id)) order.push(s.id);
+    map.set(s.id, s);
+  }
+  return order.map((id) => map.get(id) as Source);
+}
+
+/**
+ * `draftedSections` 用 reducer。`sectionId` 単位で last-write-wins し、
+ * 同じセクションを再ドラフトしたときに重複行が増えないようにする。
+ *
+ * Merge drafted sections by `sectionId`.
+ */
+function mergeSectionsById(
+  prev: DraftedSection[],
+  next: DraftedSection[] | undefined,
+): DraftedSection[] {
+  if (!next || next.length === 0) return prev;
+  const order: string[] = [];
+  const map = new Map();
+  for (const s of prev) {
+    if (!map.has(s.sectionId)) order.push(s.sectionId);
+    map.set(s.sectionId, s);
+  }
+  for (const s of next) {
+    if (!map.has(s.sectionId)) order.push(s.sectionId);
+    map.set(s.sectionId, s);
+  }
+  return order.map((id) => map.get(id) as DraftedSection);
+}
+
+/**
+ * Wiki Compose orchestrator state schema.
+ *
+ * Channel groups:
+ * 1. `BaseState` — messages, phase, pageId, userId.
+ * 2. Research mirror — superset of `ResearchLoopState` channels so the
+ *    compiled research subgraph composes as a node and state flows through.
+ * 3. Brief — `pageSnapshot`, `briefQuestions`, `brief`.
+ * 4. Structure — `outlineProposal`, `approvedOutline`.
+ * 5. Draft / completion — `draftedSections`, `completion`.
+ */
+export const WikiComposeState = Annotation.Root({
+  ...BaseState.spec,
+
+  // ── Brief phase ───────────────────────────────────────────────────────────
+  /** Page snapshot loaded once at session start. */
+  pageSnapshot: Annotation({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+  /** Brief 質問群（0..7）。`briefDialogue` が一度だけ全置換する。 */
+  briefQuestions: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** Brief 確定結果。`humanReviewBrief` が resume payload を投影する。 */
+  brief: Annotation({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+
+  // ── Research mirror (matches ResearchLoopState exactly) ──────────────────
+  /** 現在のループ回数（research subgraph が書く）。 */
+  iteration: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => 0,
+  }),
+  /** ループ上限（Brief で 1..5 にユーザー設定可、デフォルト 3）。 */
+  maxIterations: Annotation({
+    reducer: (prev, next) => next ?? prev,
+    default: () => 3,
+  }),
+  /** Research subgraph 内の直近クエリ。 */
+  queries: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 蓄積調査ソース（research subgraph が書く）。 */
+  pendingSources: Annotation({
+    reducer: mergeSourcesById,
+    default: () => [],
+  }),
+  /** 直近の評価。 */
+  lastEvaluation: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  /** 終了理由。 */
+  exitReason: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => null,
+  }),
+  /** 各ループの compile_batch スナップショット。 */
+  batches: Annotation({
+    reducer: (prev, next) => (next === undefined ? prev : [...prev, ...next]),
+    default: () => [],
+  }),
+  /** 採用ソース。`human_review_research` が resume 値から projection する。 */
+  approvedResearch: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 除外ソース。 */
+  rejectedResearch: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** 追加調査リクエスト（route 経由で投入）。 */
+  additionalRequest: Annotation({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+
+  // ── Structure phase ──────────────────────────────────────────────────────
+  /** Orchestrator が提案する初期アウトライン。 */
+  outlineProposal: Annotation({
+    reducer: (_prev, next) => next,
+    default: () => [],
+  }),
+  /** ユーザー承認後の確定アウトライン。 */
+  approvedOutline: Annotation({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+
+  // ── Draft / completion ───────────────────────────────────────────────────
+  /** 確定済みセクション本文。`draftSections` が 1 セクションずつ append する。 */
+  draftedSections: Annotation({
+    reducer: mergeSectionsById,
+    default: () => [],
+  }),
+  /** 完了サマリ。`completed` ノードが書く。 */
+  completion: Annotation({
+    reducer: (prev, next) => (next === undefined ? prev : next),
+    default: () => null,
+  }),
+});
+
+/** `WikiComposeState.State` のショートカット。 */
+export type WikiComposeStateType = typeof WikiComposeState.State;
+
+/** `WikiComposeState.Update` のショートカット。ノードの戻り値型。 */
+export type WikiComposeStateUpdate = typeof WikiComposeState.Update;
diff --git a/server/api/src/agents/graphs/wikiCompose/types.ts b/server/api/src/agents/graphs/wikiCompose/types.ts
new file mode 100644
index 00000000..91ec2c83
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/types.ts
@@ -0,0 +1,212 @@
+/**
+ * Shared value types for the Wiki Compose orchestrator graph (#950 / P2).
+ *
+ * Wiki Compose 全体グラフが扱う値型。
+ * `WikiComposeState` (state.ts) と各ノードが参照する。
+ *
+ * Pure data types referenced by `WikiComposeState` and the orchestrator nodes.
+ * Kept separate from `Annotation.Root` so non-LangGraph modules (frontend
+ * wire types, vitest fixtures) can import without pulling LangGraph runtime.
+ */
+
+import type { Source } from "../../subgraphs/research/types.js";
+
+/** Re-exported here so orchestrator nodes can import everything from one barrel. */
+export type { Source };
+
+/**
+ * Brief フェーズで Orchestrator が生成する 1 つの構造化質問。
+ *
+ * One structured Brief question. Brief never opens a free-form chat; the
+ * frontend renders this as a question card with selectable options + an
+ * optional free-text addendum. `0..7` questions are emitted (the Orchestrator
+ * decides; `0` means "skip Brief entirely").
+ */
+export interface BriefQuestion {
+  /** Stable uuid. */
+  id: string;
+  /** Question text shown to the user. */
+  question: string;
+  /**
+   * Optional rationale shown as helper text. Surfaced so the user understands
+   * why each question matters.
+   */
+  rationale?: string;
+  /**
+   * Answer choices (option chips). When empty, the UI renders a single
+   * free-text input. The frontend always allows a free-text addendum on top
+   * of any chip selection.
+   */
+  options: BriefOption[];
+  /** Whether the user MUST answer this question to proceed. */
+  required: boolean;
+}
+
+/** One selectable option chip in a {@link BriefQuestion}. */
+export interface BriefOption {
+  /** Stable id within the question (used by the resume payload). */
+  id: string;
+  /** Display label. */
+  label: string;
+  /** Optional follow-up hint shown when this option is selected. */
+  hint?: string;
+}
+
+/**
+ * User's reply to a single Brief question. Resume payload value.
+ *
+ * Brief 質問への 1 件分の回答（resume payload の単位）。
+ */
+export interface BriefAnswer {
+  /** Question id this answer responds to. */
+  questionId: string;
+  /** Selected option ids (may be empty when only free-text is provided). */
+  selectedOptionIds: string[];
+  /** Optional free-text addendum (always allowed). */
+  freeText?: string;
+}
+
+/**
+ * Aggregated Brief result projected into state after the user resumes.
+ *
+ * Brief 完了時に state に投影される確定回答セット。`structureDialogue` と
+ * `researchPhase` がプロンプト構築時にここを読む。
+ */
+export interface BriefResult {
+  /** Question/answer pairs in their original order. */
+  answers: BriefAnswer[];
+  /**
+   * Free-form natural-language summary derived from the answers. Used by
+   * downstream nodes so they do not have to re-traverse the Q&A pairs.
+   */
+  summary: string;
+  /**
+   * Optional addition mode flag — populated when the page already has body
+   * content and the user chose "append" instead of "replace". The draft
+   * phase reads this to decide whether to write into a fresh document or to
+   * merge with the existing body.
+   */
+  appendToExisting: boolean;
+}
+
+/**
+ * Page snapshot loaded at session start. Used by Brief to surface the
+ * current page state and by Draft to know whether to append vs replace.
+ *
+ * セッション開始時に読み込むページのスナップショット。Brief / Draft が参照する。
+ */
+export interface PageSnapshot {
+  pageId: string;
+  /** Wiki page title. */
+  title: string;
+  /** Existing body markdown (may be empty). */
+  body: string;
+  /** True when `body.trim().length > 0`. */
+  hasContent: boolean;
+}
+
+/**
+ * Structure フェーズで生成された 1 つのアウトライン項目。
+ *
+ * Single outline node. The orchestrator emits a flat or 1-level nested list;
+ * the frontend supports drag-and-drop reordering before approval.
+ */
+export interface OutlineSection {
+  /** Stable uuid. */
+  id: string;
+  /** Section heading text (without `# ` prefix). */
+  heading: string;
+  /** Heading depth (1 = top-level h2, 2 = h3, …; the page title itself is h1). */
+  depth: number;
+  /**
+   * Short description / what to cover. Surfaced as helper text in the outline
+   * editor and consumed by the draft node as the section brief.
+   */
+  intent: string;
+  /**
+   * Optional list of source ids (from `approvedResearch`) that the user
+   * marked as relevant for this section. Populated post-approval via the
+   * outline resume payload.
+   */
+  sourceIds?: string[];
+}
+
+/**
+ * Outline approved by the user via the `human_review_outline` interrupt.
+ *
+ * `humanReviewOutline` が resume payload を投影して作る。Draft フェーズが
+ * 各セクションを順に LLM ストリームで書き起こす。
+ */
+export interface ApprovedOutline {
+  /** Final ordered sections (after user edits). */
+  sections: OutlineSection[];
+}
+
+/**
+ * Section draft result. One per outline section, filled in by
+ * `draft_sections` as it streams.
+ *
+ * 確定済みの 1 セクション分本文。各セクションは LLM トークンストリームで
+ * 書き起こされ、確定後に本配列へ append される。
+ */
+export interface DraftedSection {
+  /** Matches {@link OutlineSection.id}. */
+  sectionId: string;
+  /** Final heading (may differ if user renamed mid-flight). */
+  heading: string;
+  /** Final markdown body for the section (excluding the heading). */
+  body: string;
+  /** Source ids cited in this section (subset of `approvedResearch`). */
+  citedSourceIds: string[];
+  /** ISO timestamp when the section completed. */
+  completedAt: string;
+}
+
+/**
+ * Final compose output stamped onto state at the `completed` node.
+ *
+ * 完了時のサマリ。フロントは `/notes/:noteId/:pageId` に戻るときの最終本文を
+ * ここから読む。
+ */
+export interface ComposeCompletion {
+  /** Final markdown body (sections joined). */
+  markdown: string;
+  /** Sections in their final order. */
+  sections: DraftedSection[];
+  /** Approved sources collated for citation export. */
+  citedSources: Source[];
+  /** ISO timestamp at completion. */
+  completedAt: string;
+}
+
+/**
+ * Discriminated union of the values emitted by the orchestrator's interrupt
+ * nodes. Surfaces on the wire as `SseInterruptEvent.payload`.
+ *
+ * 各 interrupt ノードが `interrupt(value)` で渡すペイロード。フロントは
+ * `kind` で分岐して UI を出し分ける。
+ */
+export type WikiComposeInterruptPayload =
+  | { kind: "human_review_brief"; questions: BriefQuestion[]; pageSnapshot: PageSnapshot }
+  | { kind: "human_review_research"; batchId: string | null; pendingSources: Source[] }
+  | { kind: "human_review_outline"; outline: OutlineSection[]; approvedSources: Source[] };
+
+/**
+ * Resume payloads expected at each interrupt point. Each is validated at the
+ * node boundary via the matching zod schema in `resumeSchemas.ts`.
+ *
+ * 各 interrupt 点の resume payload TS 型。実体は zod で検証する。
+ */
+export interface BriefResumeInput {
+  answers: BriefAnswer[];
+  /** True when the user chose "append to existing body" (U2). */
+  appendToExisting?: boolean;
+  /** Optional override for the research loop's max iterations (1..5). */
+  researchMaxIterations?: number;
+}
+
+/** Resume payload for the outline interrupt. */
+export interface OutlineResumeInput {
+  /** Final outline (reordered / edited by the user). */
+  sections: OutlineSection[];
+}
diff --git a/server/api/src/agents/graphs/wikiCompose/wikiComposeGraph.ts b/server/api/src/agents/graphs/wikiCompose/wikiComposeGraph.ts
new file mode 100644
index 00000000..c23b3d51
--- /dev/null
+++ b/server/api/src/agents/graphs/wikiCompose/wikiComposeGraph.ts
@@ -0,0 +1,141 @@
+/**
+ * Wiki Compose P2 — `wikiComposeGraph` orchestrator (issue #950).
+ *
+ * Brief → Research → Structure → Draft → Completed の全体フローを担う
+ * LangGraph オーケストレータ。`researchLoopSubgraph` (#949 / P1) を **subgraph
+ * as node** として組み込み、ループ内 interrupt
+ * (`human_review_research`) は親グラフから見ても通常の interrupt として伝播する
+ * （状態は `WikiComposeState` の superset 設計により自動共有）。
+ *
+ * Top-level orchestrator. The research subgraph composes as a node so a
+ * single PostgresSaver thread services Brief → Research → Outline → Draft.
+ * Each interrupt halts the same `thread_id` and resumes through the same
+ * `PATCH /resume` route.
+ *
+ * Pipeline:
+ *
+ * ```
+ * START
+ *   → brief_dialogue
+ *   → human_review_brief                       [interrupt #1]
+ *   → research_subgraph (= researchLoopSubgraph)
+ *       └── plan → search → fetch → eval → … → human_review_research  [interrupt #2]
+ *   → structure_dialogue
+ *   → human_review_outline                     [interrupt #3]
+ *   → draft_sections
+ *   → completed
+ *   → END
+ * ```
+ */
+import { END, START, StateGraph } from "@langchain/langgraph";
+import { WikiComposeState } from "./state.js";
+import {
+  registerGraph,
+  type GraphFactory,
+  type GraphFactoryInput,
+  type CompiledGraphLike,
+} from "../../registry/graphRegistry.js";
+import {
+  planQueries,
+  webSearch,
+  wikiSearch,
+  fetchArticles,
+  evaluateSufficiency,
+  refineQueries,
+  compileBatch,
+  humanReviewResearch,
+} from "../../subgraphs/research/nodes/index.js";
+import {
+  briefDialogue,
+  humanReviewBrief,
+  structureDialogue,
+  humanReviewOutline,
+  draftSections,
+  completed,
+} from "./nodes/index.js";
+import { shouldRefine } from "../../subgraphs/research/researchGraph.js";
+
+/** Registered graph id. */
+export const WIKI_COMPOSE_GRAPH_ID = "wiki-compose" as const;
+/** Registered graph version. Bump when behaviour changes meaningfully. */
+export const WIKI_COMPOSE_GRAPH_VERSION = "1.0.0";
+
+/**
+ * Inlined research nodes vs separate subgraph: we inline the research nodes
+ * at the orchestrator level so the parent state's `iteration` / `queries` /
+ * `pendingSources` channels are written directly and the interrupt at
+ * `human_review_research` halts the parent thread_id without a translation
+ * layer. This is equivalent to subgraph-as-node composition since the
+ * orchestrator state is a strict superset of `ResearchLoopState` (see
+ * `state.ts`).
+ *
+ * 研究ノードは orchestrator state 上に直接配置する。state を superset 設計に
+ * したので state は自動共有され、interrupt は親 thread_id で halt する。
+ */
+const factory: GraphFactory = ({ checkpointer }: GraphFactoryInput): CompiledGraphLike => {
+  const builder = new StateGraph(WikiComposeState)
+    // Brief phase
+    .addNode("brief_dialogue", briefDialogue)
+    .addNode("human_review_brief", humanReviewBrief)
+    // Research phase (inlined research subgraph nodes, sharing state)
+    .addNode("plan_queries", planQueries)
+    .addNode("web_search", webSearch)
+    .addNode("wiki_search", wikiSearch)
+    .addNode("fetch_articles", fetchArticles)
+    .addNode("evaluate_sufficiency", evaluateSufficiency)
+    .addNode("refine_queries", refineQueries)
+    .addNode("compile_batch", compileBatch)
+    .addNode("human_review_research", humanReviewResearch)
+    // Structure phase
+    .addNode("structure_dialogue", structureDialogue)
+    .addNode("human_review_outline", humanReviewOutline)
+    // Draft + completion
+    .addNode("draft_sections", draftSections)
+    .addNode("completed", completed)
+    // Edges
+    .addEdge(START, "brief_dialogue")
+    .addEdge("brief_dialogue", "human_review_brief")
+    .addEdge("human_review_brief", "plan_queries")
+    // Research loop (mirrors researchLoopSubgraph wiring).
+    .addEdge("plan_queries", "web_search")
+    .addEdge("plan_queries", "wiki_search")
+    .addEdge("web_search", "fetch_articles")
+    .addEdge("wiki_search", "fetch_articles")
+    .addEdge("fetch_articles", "evaluate_sufficiency")
+    .addConditionalEdges("evaluate_sufficiency", shouldRefine, {
+      refine: "refine_queries",
+      compile: "compile_batch",
+    })
+    .addEdge("refine_queries", "web_search")
+    .addEdge("refine_queries", "wiki_search")
+    .addEdge("compile_batch", "human_review_research")
+    .addEdge("human_review_research", "structure_dialogue")
+    // Structure phase.
+    .addEdge("structure_dialogue", "human_review_outline")
+    .addEdge("human_review_outline", "draft_sections")
+    // Draft + completion.
+    .addEdge("draft_sections", "completed")
+    .addEdge("completed", END);
+
+  return checkpointer ? builder.compile({ checkpointer }) : builder.compile();
+};
+
+/**
+ * Register the Wiki Compose orchestrator graph. Idempotent.
+ *
+ * `app.ts` から `registerResearchLoopGraph()` と並べて呼ぶ。再登録は registry が
+ * 上書きで吸収する。
+ */
+export function registerWikiComposeGraph(): void {
+  registerGraph({
+    id: WIKI_COMPOSE_GRAPH_ID,
+    version: WIKI_COMPOSE_GRAPH_VERSION,
+    phase: "orchestrator",
+    description:
+      "Wiki Compose P2: full orchestrator. Brief → research → structure → draft → completed. " +
+      "Embeds the P1 research loop in-place via shared state (orchestrator state is a strict " +
+      "superset of ResearchLoopState). Three interrupt points: human_review_brief, " +
+      "human_review_research, human_review_outline.",
+    factory,
+  });
+}
diff --git a/server/api/src/agents/index.ts b/server/api/src/agents/index.ts
index f5747a37..496db34f 100644
--- a/server/api/src/agents/index.ts
+++ b/server/api/src/agents/index.ts
@@ -86,3 +86,27 @@ export {
   type ResearchResumeParsed,
   type HumanReviewInterruptPayload,
 } from "./subgraphs/research/index.js";
+export {
+  WIKI_COMPOSE_GRAPH_ID,
+  WIKI_COMPOSE_GRAPH_VERSION,
+  registerWikiComposeGraph,
+  WikiComposeState,
+  type WikiComposeStateType,
+  type WikiComposeStateUpdate,
+  briefResumeSchema,
+  type BriefResumeParsed,
+  outlineResumeSchema,
+  type OutlineResumeParsed,
+  type BriefAnswer,
+  type BriefOption,
+  type BriefQuestion,
+  type BriefResult,
+  type BriefResumeInput,
+  type ApprovedOutline,
+  type ComposeCompletion,
+  type DraftedSection,
+  type OutlineResumeInput,
+  type OutlineSection,
+  type PageSnapshot,
+  type WikiComposeInterruptPayload,
+} from "./graphs/wikiCompose/index.js";
diff --git a/server/api/src/agents/runner/sseMapper.ts b/server/api/src/agents/runner/sseMapper.ts
index 986db56f..18211704 100644
--- a/server/api/src/agents/runner/sseMapper.ts
+++ b/server/api/src/agents/runner/sseMapper.ts
@@ -11,6 +11,8 @@
  * file only describes the shape transformation so unit tests can pin it.
  */
 import type {
+  SseComposePhaseEvent,
+  SseComposeSectionEvent,
   SseEvent,
   SseResearchBatchEvent,
   SseResearchEvaluationEvent,
@@ -208,6 +210,10 @@ function mapCustomEvent(event: LangGraphRuntimeEvent): SseEvent[] {
       return mapResearchEvaluation(data);
     case "research_batch":
       return mapResearchBatch(data);
+    case "compose_phase":
+      return mapComposePhase(data);
+    case "compose_section":
+      return mapComposeSection(data);
     default:
       // Unknown custom event names are dropped silently; emitting them as `status`
       // would risk leaking implementation detail to the wire.
@@ -236,6 +242,40 @@ function mapResearchEvaluation(data: Record): SseResearchEvalua
   return [{ type: "research_evaluation", iteration, score, rationale, missingAspectsCount }];
 }
 
+function mapComposePhase(data: Record): SseComposePhaseEvent[] {
+  const phase = data.phase;
+  const status = data.status;
+  if (
+    phase !== "brief" &&
+    phase !== "research" &&
+    phase !== "structure" &&
+    phase !== "draft" &&
+    phase !== "completed"
+  ) {
+    return [];
+  }
+  if (status !== "entered" && status !== "completed") return [];
+  return [{ type: "compose_phase", phase, status }];
+}
+
+function mapComposeSection(data: Record): SseComposeSectionEvent[] {
+  const sectionId = typeof data.sectionId === "string" ? data.sectionId : null;
+  const heading = typeof data.heading === "string" ? data.heading : null;
+  const status = data.status === "started" || data.status === "completed" ? data.status : null;
+  const index = typeof data.index === "number" ? data.index : null;
+  const total = typeof data.total === "number" ? data.total : null;
+  if (
+    sectionId === null ||
+    heading === null ||
+    status === null ||
+    index === null ||
+    total === null
+  ) {
+    return [];
+  }
+  return [{ type: "compose_section", sectionId, heading, status, index, total }];
+}
+
 function mapResearchBatch(data: Record): SseResearchBatchEvent[] {
   const batchId = typeof data.batchId === "string" ? data.batchId : null;
   const iteration = typeof data.iteration === "number" ? data.iteration : null;
diff --git a/server/api/src/app.ts b/server/api/src/app.ts
index 03fc3424..8c5cb282 100644
--- a/server/api/src/app.ts
+++ b/server/api/src/app.ts
@@ -46,6 +46,7 @@ import internalRoutes from "./routes/internal.js";
 import composeSessionRoutes from "./routes/composeSessions.js";
 import { registerStubGraph } from "./agents/registry/stubGraph.js";
 import { registerResearchLoopGraph } from "./agents/subgraphs/research/index.js";
+import { registerWikiComposeGraph } from "./agents/graphs/wikiCompose/index.js";
 
 /**
  * Creates and configures the Hono API app (routes, CORS, etc.).
@@ -55,11 +56,13 @@ export function createApp(): Hono {
   // Wiki Compose graphs を registry に登録する。いずれも idempotent。
   // - `wiki-compose-stub` — P0 smoke test (#948)
   // - `wiki-compose-research` — P1 自律調査ループ (#949)
+  // - `wiki-compose` — P2 全体オーケストレータ (#950)
   //
-  // Register all Wiki Compose graphs. Both calls are idempotent across hot
+  // Register all Wiki Compose graphs. Calls are idempotent across hot
   // reloads (registry uses `Map#set` so the latest registration wins).
   registerStubGraph();
   registerResearchLoopGraph();
+  registerWikiComposeGraph();
 
   const app = new Hono();
   const wildcard = isWildcardCors();
diff --git a/server/api/src/routes/composeSessions.ts b/server/api/src/routes/composeSessions.ts
index e4b53de5..7d458a25 100644
--- a/server/api/src/routes/composeSessions.ts
+++ b/server/api/src/routes/composeSessions.ts
@@ -58,6 +58,7 @@ import { SSE_EVENT_NAMES, type SseEvent } from "../agents/core/types/sseEvents.j
 import { GRAPH_CONTEXT_CONFIG_KEY } from "../agents/core/types/graphContext.js";
 import { resolveCheckpointerForRun } from "../agents/core/checkpoint/index.js";
 import { RESEARCH_GRAPH_ID } from "../agents/subgraphs/research/index.js";
+import { WIKI_COMPOSE_GRAPH_ID } from "../agents/graphs/wikiCompose/index.js";
 import type { AppEnv } from "../types/index.js";
 
 /**
@@ -94,14 +95,17 @@ function translateGraphInput(graphId: string, raw: unknown): unknown {
 /**
  * Per-graph recursion limit. LangGraph's default of 25 is enough for the stub
  * graph but tight for `wiki-compose-research`, which runs up to ~5 iterations
- * × ~6 nodes ≈ 30 node executions. We bump it for that graph only rather than
- * raising the global default at `graphRunner.ts:147`.
+ * × ~6 nodes ≈ 30 node executions. The full `wiki-compose` orchestrator (#950)
+ * adds Brief + Structure + Draft (up to ~10 sections × 1 node) on top of the
+ * inlined research loop, so it needs a larger budget still.
  *
  * 調査ループは最大 5 イテレーション × 約 6 ノード = ~30 node 実行になり得るため、
- * 既定の 25 では不足する。該当 graph だけ 60 に引き上げる。
+ * 既定の 25 では不足する。orchestrator (`wiki-compose`) は更に Brief / Structure /
+ * Draft フェーズ + 最大 10 セクションを足すので 120 に引き上げる。
  */
 function recursionLimitFor(graphId: string): number | undefined {
   if (graphId === RESEARCH_GRAPH_ID) return 60;
+  if (graphId === WIKI_COMPOSE_GRAPH_ID) return 120;
   return undefined;
 }
 
diff --git a/src/App.tsx b/src/App.tsx
index 82cacb58..62d46104 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -32,6 +32,7 @@ import SearchResults from "./pages/SearchResults";
 import NotFound from "./pages/NotFound";
 import NoteView from "./pages/NoteView";
 import NotePageView from "./pages/NotePageView";
+import WikiComposePage from "./pages/WikiComposePage";
 import NoteSettings from "./pages/NoteSettings";
 import GeneralSection from "./pages/NoteSettings/sections/GeneralSection";
 import VisibilitySection from "./pages/NoteSettings/sections/VisibilitySection";
@@ -290,6 +291,14 @@ const App = () => (
                       
                       } />
                       } />
+                      {/* Wiki Compose split-screen UI (issue #950).
+                          `/notes/:noteId/:pageId/compose` で新規セッション、
+                          `/notes/:noteId/:pageId/compose/:sessionId` で再開。 */}
+                      } />
+                      }
+                      />
                       {/* Legacy path — redirect `/notes/:noteId/pages/:pageId` to
                           the shorter `/notes/:noteId/:pageId`.
                           旧パス `/notes/:noteId/pages/:pageId` を短縮形にリダイレクト。 */}
diff --git a/src/components/editor/WikiGeneratorButton.tsx b/src/components/editor/WikiGeneratorButton.tsx
index c26a825b..5998109b 100644
--- a/src/components/editor/WikiGeneratorButton.tsx
+++ b/src/components/editor/WikiGeneratorButton.tsx
@@ -17,16 +17,40 @@ import { isAIConfigured } from "@/lib/aiSettings";
 interface WikiGeneratorButtonProps {
   title: string;
   hasContent: boolean;
-  /** 生成を開始するコールバック */
+  /**
+   * インラインWiki生成（旧 useWikiGenerator）のコールバック。`composeHref` を
+   * 渡したときは Compose 画面に遷移するため呼ばれない。Inline generation
+   * callback (legacy path); skipped when `composeHref` is provided.
+   */
   onGenerate: () => void;
   /** 現在の生成ステータス */
   status: WikiGeneratorStatus;
   disabled?: boolean;
+  /**
+   * Wiki Compose 画面の遷移先 URL。指定時はクリックで navigate し、本文ありでも
+   * ボタンを表示する (Compose は追記モードをサポートするため、issue #950 U2)。
+   *
+   * When provided, the button navigates to the Wiki Compose split-screen UI
+   * instead of calling `onGenerate`, and visibility no longer requires
+   * `hasContent === false` (Compose supports the append-mode flow per #950 U2).
+   */
+  composeHref?: string;
 }
 
 /**
- * Wiki 生成ボタン。タイトルがあり、本文が未入力のときだけ表示する。
- * Wiki generation button shown only when the note has a title and no body yet.
+ * Wiki 生成ボタン。
+ *
+ * - `composeHref` 未指定（旧経路）: タイトルがあり本文が未入力のときだけ表示し、
+ *   クリックで `onGenerate` を呼ぶ。
+ * - `composeHref` 指定（新経路, #950）: タイトルがあれば本文有無に関わらず表示し、
+ *   クリックで Compose 画面に navigate する。
+ *
+ * Wiki generation button.
+ *
+ * - Without `composeHref` (legacy): shows only when there is a title and no
+ *   body content; click invokes the inline `onGenerate` callback.
+ * - With `composeHref` (issue #950): shows whenever there is a title (Compose
+ *   handles append vs replace internally); click navigates to the Compose UI.
  */
 export const WikiGeneratorButton: React.FC = ({
   title,
@@ -34,17 +58,27 @@ export const WikiGeneratorButton: React.FC = ({
   onGenerate,
   status,
   disabled = false,
+  composeHref,
 }) => {
   const navigate = useNavigate();
   const location = useLocation();
   const [showNotConfiguredDialog, setShowNotConfiguredDialog] = React.useState(false);
 
-  // タイトルがない、または本文がある場合はボタンを非表示
-  const shouldShowButton = title.trim() !== "" && !hasContent;
+  // タイトルがない場合は常に非表示。
+  // Compose 経路では本文ありでも表示する (#950 U2: append default)。
+  // 旧経路では本文ありなら非表示 (inline generation はページを上書きするため)。
+  const hasTitle = title.trim() !== "";
+  const shouldShowButton = composeHref ? hasTitle : hasTitle && !hasContent;
 
   const isGenerating = status === "generating";
 
   const handleClick = async () => {
+    // Compose 経路: 認可チェック不要（Compose 画面で実行する）。
+    // Compose path: no AI-config check; the Compose UI handles it server-side.
+    if (composeHref) {
+      navigate(composeHref);
+      return;
+    }
     // AI が利用可能か確認（api_server モードでは API キー不要）。
     // Check AI availability (no API key required in api_server mode).
     const configured = await isAIConfigured();
@@ -87,7 +121,7 @@ export const WikiGeneratorButton: React.FC = ({
           
         
         
-          
            AIでWikipedia風の解説を生成
            
+          
            {composeHref ? "AI と対話しながら Wiki を作成" : "AIでWikipedia風の解説を生成"}
            
                     
       
 
diff --git a/src/components/note/PageEditorContent.tsx b/src/components/note/PageEditorContent.tsx
index 3673572d..0bc45896 100644
--- a/src/components/note/PageEditorContent.tsx
+++ b/src/components/note/PageEditorContent.tsx
@@ -124,6 +124,12 @@ interface PageEditorContentProps {
    * Trailing control rendered beside the floating Wiki Link input bar.
    */
   bottomBarTrailingAction?: React.ReactNode;
+  /**
+   * Wiki Compose 画面 (`/compose`) への遷移先 URL。指定すると `WikiGeneratorButton`
+   * が Compose 画面に遷移する経路を取り、本文ありでも表示される (#950 U2)。
+   * Pass-through to the WikiGeneratorButton's `composeHref`.
+   */
+  wikiComposeHref?: string;
 }
 
 /**
@@ -157,6 +163,7 @@ export const PageEditorContent: React.FC = ({
   pageActionHubRef,
   pageNoteId = null,
   bottomBarTrailingAction,
+  wikiComposeHref,
 }) => {
   const isEditorReadOnly = isReadOnly ?? isWikiGenerating;
   const hasContent = useMemo(() => isContentNotEmpty(content), [content]);
@@ -198,13 +205,25 @@ export const PageEditorContent: React.FC = ({
               onEnterMoveToContent={!isEditorReadOnly ? focusContent : undefined}
             />
           
-          {wikiStatus && onGenerateWiki && (
+          {/* Wiki 生成ボタンの表示条件:
+              - 旧経路: `wikiStatus` + `onGenerateWiki` 両方ある場合（インライン生成）
+              - 新経路: `wikiComposeHref` がある場合（Compose 画面に遷移、#950）
+              いずれも `WikiGeneratorButton` 自身がタイトル / 本文条件で更に
+              フィルタする。
+
+              Show the Wiki generation button when either:
+              - legacy: both `wikiStatus` + `onGenerateWiki` are supplied
+                (inline generation), or
+              - new: `wikiComposeHref` is supplied (navigate to Compose, #950).
+              `WikiGeneratorButton` itself filters on title/content state. */}
+          {((wikiStatus && onGenerateWiki) || wikiComposeHref) && (
             
            
                undefined)}
+                status={wikiStatus ?? "idle"}
+                composeHref={wikiComposeHref}
               />
             
            
           )}
diff --git a/src/components/wikiCompose/ActivitySection.tsx b/src/components/wikiCompose/ActivitySection.tsx
new file mode 100644
index 00000000..739efe13
--- /dev/null
+++ b/src/components/wikiCompose/ActivitySection.tsx
@@ -0,0 +1,89 @@
+/**
+ * `ActivitySection` — agent activity timeline (#950).
+ *
+ * Compose 右ペイン下部のアクティビティタイムライン。SSE で来るツール呼び出し /
+ * 調査イテレーション / フェーズ遷移を時系列で表示し、エージェントが何を
+ * しているかを可視化する。Compose 中盤の「無音」を避けるための重要な UI。
+ *
+ * Read-only timeline. Newest entries at the bottom. Auto-scrolls into view
+ * when new rows arrive.
+ */
+import React, { useEffect, useRef } from "react";
+import { ScrollArea } from "@zedi/ui";
+import { cn } from "@zedi/ui";
+import { Check, Circle, AlertCircle, Loader2 } from "lucide-react";
+import type { ComposeActivity } from "@/hooks/useWikiComposeSession";
+
+export interface ActivitySectionProps {
+  activity: ComposeActivity[];
+  isStreaming: boolean;
+}
+
+function Icon({ status }: { status: ComposeActivity["status"] }) {
+  switch (status) {
+    case "started":
+      return ;
+    case "completed":
+      return ;
+    case "error":
+      return ;
+    default:
+      return ;
+  }
+}
+
+/** Compact activity timeline. */
+export const ActivitySection: React.FC = ({ activity, isStreaming }) => {
+  const containerRef = useRef(null);
+
+  // Scroll to the bottom on every new entry so the user sees the latest work.
+  // 新規イベント到着時に末尾までスクロール。
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [activity]);
+
+  return (
+    
            
+      
            
+        
            
+          Activity
+        
            
+        {isStreaming ? (
+          
+             live
+          
+        ) : null}
+      
            
+      
+        
            
+          {activity.length === 0 ? (
+            
            No activity yet.
            
+          ) : (
+            activity.map((entry) => (
+              
            
+                
            
+                  
+                
            
+                
            
+                  
            {entry.label}
            
+                  {entry.detail ? (
+                    
            {entry.detail}
            
+                  ) : null}
+                
            
+              
            
+            ))
+          )}
+        
            
+                  
+    
            
+  );
+};
diff --git a/src/components/wikiCompose/BriefQuestionCard.tsx b/src/components/wikiCompose/BriefQuestionCard.tsx
new file mode 100644
index 00000000..f2da3a0b
--- /dev/null
+++ b/src/components/wikiCompose/BriefQuestionCard.tsx
@@ -0,0 +1,102 @@
+/**
+ * `BriefQuestionCard` — one structured Brief question (#950).
+ *
+ * Brief フェーズで Orchestrator が生成した 1 件の質問カード。チップ式選択肢 +
+ * 任意のフリーテキストを統合した入出力 UI。`required` の質問は未回答だと
+ * `Submit` ボタンが無効化される（親側で判定）。
+ *
+ * Renders one question with optional answer chips and a free-text addendum
+ * box. Multi-select is supported; the parent owns the answer state.
+ */
+import React from "react";
+import { cn } from "@zedi/ui";
+import { Badge, Card, CardContent, CardHeader, CardTitle, Input } from "@zedi/ui";
+import type { BriefAnswer, BriefQuestion } from "@/lib/wikiCompose/types";
+
+export interface BriefQuestionCardProps {
+  question: BriefQuestion;
+  answer: BriefAnswer | null;
+  onChange: (next: BriefAnswer) => void;
+}
+
+/** Toggles a single option id in the current selection. */
+function toggleOption(selected: string[], optionId: string): string[] {
+  return selected.includes(optionId)
+    ? selected.filter((id) => id !== optionId)
+    : [...selected, optionId];
+}
+
+/** Render one Brief question card. */
+export const BriefQuestionCard: React.FC = ({
+  question,
+  answer,
+  onChange,
+}) => {
+  const selected = answer?.selectedOptionIds ?? [];
+  const freeText = answer?.freeText ?? "";
+
+  return (
+    
+      
+        
+          {question.question}
+          {question.required ? (
+            
+              required
+            
+          ) : null}
+        
+        {question.rationale ? (
+          
            {question.rationale}
            
+        ) : null}
+                  
+      
+        {question.options.length > 0 ? (
+          
            
+            {question.options.map((option) => {
+              const active = selected.includes(option.id);
+              return (
+                
+              );
+            })}
+          
            
+        ) : null}
+
+         0 ? "Add a note (optional)…" : "Type your answer…"}
+          data-testid={`brief-freetext-${question.id}`}
+          value={freeText}
+          onChange={(e) =>
+            onChange({
+              questionId: question.id,
+              selectedOptionIds: selected,
+              freeText: e.target.value || undefined,
+            })
+          }
+        />
+                  
+                
+  );
+};
diff --git a/src/components/wikiCompose/ComposePanel.tsx b/src/components/wikiCompose/ComposePanel.tsx
new file mode 100644
index 00000000..5ec7f692
--- /dev/null
+++ b/src/components/wikiCompose/ComposePanel.tsx
@@ -0,0 +1,110 @@
+/**
+ * `ComposePanel` — right pane of the Wiki Compose split view (#950).
+ *
+ * 分割画面の右ペイン。`PhaseStepper` (top), Dialogue / Research セクション
+ * (middle), ActivitySection (bottom) を 1 つのスクロール可能カラムに積む。
+ * フェーズに応じて DialogueSection と ResearchSection の表示を出し分ける。
+ *
+ * Stacks the stepper + phase-specific dialogue panel + activity log. The
+ * actual interaction logic lives in each section component; this is just a
+ * layout wrapper.
+ */
+import React from "react";
+import { PhaseStepper } from "./PhaseStepper";
+import { DialogueSection } from "./DialogueSection";
+import { ResearchSection } from "./ResearchSection";
+import { ActivitySection } from "./ActivitySection";
+import type {
+  BriefAnswer,
+  BriefQuestion,
+  OutlineSection,
+  PageSnapshot,
+  ResearchBatch,
+  ResearchSource,
+} from "@/lib/wikiCompose/types";
+import type { ComposeActivity, ComposePhase } from "@/hooks/useWikiComposeSession";
+
+export interface ComposePanelProps {
+  phase: ComposePhase;
+  isStreaming: boolean;
+
+  briefQuestions: BriefQuestion[];
+  pageSnapshot: PageSnapshot | null;
+
+  latestBatch: ResearchBatch | null;
+  pendingSources: ResearchSource[];
+  approvedSources: ResearchSource[];
+
+  outlineProposal: OutlineSection[];
+
+  activity: ComposeActivity[];
+
+  onSubmitBrief: (input: {
+    answers: BriefAnswer[];
+    appendToExisting?: boolean;
+    researchMaxIterations?: number;
+  }) => Promise;
+  onSubmitResearchApproval: (input: {
+    approvedSourceIds: string[];
+    rejectedSourceIds?: string[];
+    note?: string;
+  }) => Promise;
+  onSubmitOutline: (input: { sections: OutlineSection[] }) => Promise;
+}
+
+/** Right pane container. */
+export const ComposePanel: React.FC = (props) => {
+  const {
+    phase,
+    isStreaming,
+    briefQuestions,
+    pageSnapshot,
+    latestBatch,
+    pendingSources,
+    approvedSources,
+    outlineProposal,
+    activity,
+    onSubmitBrief,
+    onSubmitResearchApproval,
+    onSubmitOutline,
+  } = props;
+
+  return (
+    
+  );
+};
diff --git a/src/components/wikiCompose/DialogueSection.tsx b/src/components/wikiCompose/DialogueSection.tsx
new file mode 100644
index 00000000..663e0e2c
--- /dev/null
+++ b/src/components/wikiCompose/DialogueSection.tsx
@@ -0,0 +1,238 @@
+/**
+ * `DialogueSection` — Brief / Structure interaction panel (#950).
+ *
+ * Compose 画面右ペインの「対話」セクション。フェーズに応じて Brief の質問カード
+ * 群、Structure のアウトラインエディタ、Draft 中のセクション進捗を出し分ける。
+ * Compose は free-form chat ではないため、各フェーズの UI は専用フォーム形式。
+ *
+ * Pure presentational shell that routes between the BriefQuestionCard list,
+ * OutlineEditor, and the section progress view based on `phase`. Submit
+ * handlers come from the parent (`WikiComposePage` → `useWikiComposeSession`).
+ */
+import React, { useMemo, useState } from "react";
+import { Button, Card, CardContent, CardHeader, CardTitle, Slider } from "@zedi/ui";
+import { Sparkles, RefreshCw, ArrowRight } from "lucide-react";
+import type {
+  BriefAnswer,
+  BriefQuestion,
+  OutlineSection,
+  PageSnapshot,
+} from "@/lib/wikiCompose/types";
+import { BriefQuestionCard } from "./BriefQuestionCard";
+import { OutlineEditor } from "./OutlineEditor";
+import type { ComposePhase } from "@/hooks/useWikiComposeSession";
+
+export interface DialogueSectionProps {
+  phase: ComposePhase;
+  briefQuestions: BriefQuestion[];
+  pageSnapshot: PageSnapshot | null;
+  outlineProposal: OutlineSection[];
+  isStreaming: boolean;
+  /** Brief submission. */
+  onSubmitBrief: (input: {
+    answers: BriefAnswer[];
+    appendToExisting?: boolean;
+    researchMaxIterations?: number;
+  }) => Promise;
+  /** Structure submission. */
+  onSubmitOutline: (input: { sections: OutlineSection[] }) => Promise;
+}
+
+/** Whether all required questions have at least one answer. */
+function allRequiredAnswered(
+  questions: BriefQuestion[],
+  answers: Record,
+): boolean {
+  return questions
+    .filter((q) => q.required)
+    .every((q) => {
+      const a = answers[q.id];
+      if (!a) return false;
+      const hasOption = (a.selectedOptionIds ?? []).length > 0;
+      const hasText = Boolean(a.freeText && a.freeText.trim().length > 0);
+      return hasOption || hasText;
+    });
+}
+
+/** Container for Brief / Structure / Draft dialogue UIs. */
+export const DialogueSection: React.FC = ({
+  phase,
+  briefQuestions,
+  pageSnapshot,
+  outlineProposal,
+  isStreaming,
+  onSubmitBrief,
+  onSubmitOutline,
+}) => {
+  const [answers, setAnswers] = useState>({});
+  const [appendToExisting, setAppendToExisting] = useState(
+    Boolean(pageSnapshot?.hasContent),
+  );
+  const [maxIterations, setMaxIterations] = useState(3);
+  const [submitting, setSubmitting] = useState(false);
+
+  const canSubmitBrief = useMemo(
+    () => allRequiredAnswered(briefQuestions, answers),
+    [briefQuestions, answers],
+  );
+
+  if (phase === "brief") {
+    return (
+      
            
+        
            
+          
            
+             Brief
+          
            
+          
+            {briefQuestions.length === 0
+              ? "No questions — proceed to research"
+              : `${briefQuestions.length} question${briefQuestions.length > 1 ? "s" : ""}`}
+          
+        
            
+
+        {briefQuestions.length === 0 && isStreaming ? (
+          
+            
+              Preparing Brief questions…
+            
+          
+        ) : null}
+
+        {briefQuestions.map((q) => (
+           setAnswers((prev) => ({ ...prev, [q.id]: next }))}
+          />
+        ))}
+
+        {pageSnapshot?.hasContent ? (
+          
+            
+              
+                Page already has content
+              
+            
+            
+              
+              
+            
+          
+        ) : null}
+
+        
+          
+            
+              Research depth
+            
+          
+          
+            
            
+              1 (quick)
+              
+                {maxIterations} iteration{maxIterations > 1 ? "s" : ""}
+              
+              5 (deep)
+            
            
+             setMaxIterations(v[0] ?? 3)}
+            />
+                      
+                    
+
+        
            
+          
+        
            
+      
            
+    );
+  }
+
+  if (phase === "structure") {
+    return (
+      
            
+        
            
+          
            Outline
            
+          
+            {outlineProposal.length} section{outlineProposal.length === 1 ? "" : "s"}
+          
+        
            
+         {
+            setSubmitting(true);
+            try {
+              await onSubmitOutline({ sections });
+            } finally {
+              setSubmitting(false);
+            }
+          }}
+        />
+      
            
+    );
+  }
+
+  if (phase === "draft" || phase === "completed") {
+    return (
+      
            
+        
            
+          
            
+            {phase === "completed" ? "Completed" : "Drafting"}
+          
            
+          
            
+            {phase === "completed"
+              ? "Article ready. Return to the page to review and save."
+              : "Sections are being drafted. Watch the editor on the left for live updates."}
+          
            
+        
            
+      
            
+    );
+  }
+
+  // research phase — handled in ResearchSection; nothing to render here.
+  return null;
+};
diff --git a/src/components/wikiCompose/EditorPane.tsx b/src/components/wikiCompose/EditorPane.tsx
new file mode 100644
index 00000000..eff4789e
--- /dev/null
+++ b/src/components/wikiCompose/EditorPane.tsx
@@ -0,0 +1,100 @@
+/**
+ * `EditorPane` — left pane of the Wiki Compose split view (#950).
+ *
+ * 分割画面の左ペイン。タイトル + Tiptap ベースのエディタを表示する想定だが、
+ * Compose 中の draft 進捗を確認できるよう、本実装ではセクション本文を
+ * Markdown プレビューとして直接描画する MVP に絞る。確定後 (`phase === "completed"`)
+ * は完成 Markdown を一括表示し、ユーザーはノートに戻ってから Tiptap で確定する。
+ *
+ * Read-only preview of the streaming/drafted content. Each outline section
+ * gets its own `## heading` block. The currently-streaming section is
+ * highlighted with a pulsing border so the user sees where to look.
+ */
+import React from "react";
+import { cn } from "@zedi/ui";
+import type { DraftedSection, OutlineSection } from "@/lib/wikiCompose/types";
+
+export interface EditorPaneProps {
+  title: string;
+  outline: OutlineSection[];
+  draftedSections: Record;
+  sectionBuffers: Record;
+  streamingSectionId: string | null;
+  /** Markdown preview to render when the run completes. */
+  completedMarkdown: string | null;
+}
+
+/** Render the left preview pane. */
+export const EditorPane: React.FC = ({
+  title,
+  outline,
+  draftedSections,
+  sectionBuffers,
+  streamingSectionId,
+  completedMarkdown,
+}) => {
+  return (
+    
            
+      
            {title || "Untitled page"}
            
+
+      {outline.length === 0 && !completedMarkdown ? (
+        
            
+          The article will appear here once the agent starts drafting.
+        
            
+      ) : null}
+
+      {outline.length > 0 ? (
+        
            
+          {outline.map((section) => {
+            const drafted = draftedSections[section.id];
+            const buffer = sectionBuffers[section.id] ?? "";
+            const isStreaming = streamingSectionId === section.id;
+            const body = drafted?.body ?? buffer;
+            return (
+              
            
+                {section.depth === 1 ? (
+                  
            {section.heading}
            
+                ) : (
+                  
            {section.heading}
            
+                )}
+                {body.trim().length === 0 ? (
+                  
            
+                    {isStreaming ? "Streaming…" : section.intent}
+                  
            
+                ) : (
+                  // Plain-text rendering of the running buffer. Once the
+                  // section finalises we still render as 
             to preserve
+                  // formatting; a future iteration can mount Tiptap here.
+                  // 進行中はバッファをそのまま 
             で出す（フォーマット保持）。
+                  
            +                    {body}
+                  
            
+                )}
+              
            
+            );
+          })}
+        
            
+      ) : null}
+
+      {completedMarkdown ? (
+        
            
+          
            Final Markdown
            
+          
            +            {completedMarkdown}
+          
            
+        
            
+      ) : null}
+    
            
+  );
+};
diff --git a/src/components/wikiCompose/OutlineEditor.tsx b/src/components/wikiCompose/OutlineEditor.tsx
new file mode 100644
index 00000000..8d80e2a1
--- /dev/null
+++ b/src/components/wikiCompose/OutlineEditor.tsx
@@ -0,0 +1,170 @@
+/**
+ * `OutlineEditor` — editable outline list for the Structure phase (#950).
+ *
+ * Orchestrator が提案したアウトラインをユーザーが編集 (並び替え / リネーム /
+ * depth 変更 / 削除) するための軽量 UI。ドラッグ&ドロップは将来対応とし、
+ * 当面は上下矢印ボタンで順序入れ替えする。
+ *
+ * Minimal accessible outline editor. Each section row has heading + intent
+ * inputs, depth toggle (h2 ↔ h3), move-up / move-down buttons, and a delete
+ * button. The user submits via the dedicated button at the bottom.
+ */
+import React, { useState } from "react";
+import { ArrowDown, ArrowUp, Trash2, Plus, Check } from "lucide-react";
+import { Button, Card, CardContent, Input, Textarea } from "@zedi/ui";
+import { cn } from "@zedi/ui";
+import type { OutlineSection } from "@/lib/wikiCompose/types";
+
+let nextLocalId = 0;
+function makeLocalId(): string {
+  nextLocalId += 1;
+  return `local-${nextLocalId}-${Date.now()}`;
+}
+
+export interface OutlineEditorProps {
+  initialSections: OutlineSection[];
+  disabled?: boolean;
+  onSubmit: (sections: OutlineSection[]) => Promise;
+}
+
+/** Render an editable outline. */
+export const OutlineEditor: React.FC = ({
+  initialSections,
+  disabled = false,
+  onSubmit,
+}) => {
+  const [sections, setSections] = useState(initialSections);
+  const [submitting, setSubmitting] = useState(false);
+
+  React.useEffect(() => {
+    setSections(initialSections);
+  }, [initialSections]);
+
+  const move = (index: number, direction: -1 | 1) => {
+    setSections((prev) => {
+      const next = [...prev];
+      const target = index + direction;
+      if (target < 0 || target >= next.length) return prev;
+      const item = next[index];
+      const other = next[target];
+      if (!item || !other) return prev;
+      next[index] = other;
+      next[target] = item;
+      return next;
+    });
+  };
+
+  const remove = (id: string) => setSections((prev) => prev.filter((s) => s.id !== id));
+
+  const add = () =>
+    setSections((prev) => [
+      ...prev,
+      { id: makeLocalId(), heading: "New section", depth: 1, intent: "" },
+    ]);
+
+  const update = (id: string, patch: Partial) =>
+    setSections((prev) => prev.map((s) => (s.id === id ? { ...s, ...patch } : s)));
+
+  const isSubmittable = sections.length > 0 && sections.every((s) => s.heading.trim().length > 0);
+
+  return (
+    
            
+      {sections.map((section, i) => (
+         1 && "ml-6")}
+        >
+          
+            
            
+               update(section.id, { heading: e.target.value })}
+                placeholder="Section heading"
+                disabled={disabled}
+              />
+              
+              
+              
+              
+            
            
+