From 29ec6f3ab38a4029460879d15b97c3c77f118c28 Mon Sep 17 00:00:00 2001
From: Joseph Zaki <325440518+jz-krono@users.noreply.github.com>
Date: Sun, 4 Oct 2026 06:09:59 +0900
Subject: [PATCH] fix: bind reviewed-page retries to saved draft

---
 README.md                          |  2 +-
 src/client/PageReviewCard.tsx      | 77 +++++++++++++++++-------------
 src/client/page-review-decision.ts | 31 ++++++++++--
 src/server/page-routes.ts          |  7 +--
 src/server/pages.ts                | 66 ++++++++++++++++++-------
 src/shared/page-review.ts          |  1 +
 tests/page-review.test.tsx         | 32 ++++++++++++-
 tests/page-routes.test.ts          | 47 ++++++++++++++++++
 tests/pages.test.ts                | 57 ++++++++++++++++++++++
 9 files changed, 259 insertions(+), 61 deletions(-)

diff --git a/README.md b/README.md
index 49dfde40..40c27ba7 100644
--- a/README.md
+++ b/README.md
@@ -80,7 +80,7 @@ _Ask Scout to open a website, summarize it, save notes, and verify the file. Eve
 
 ### Review before saving
 
-Ask a Dot to show a draft before saving it. A CopilotKit human-in-the-loop card pauses the conversation for **Approve & save** or **Decline**. Approval creates the page in an authorized Space and returns a link; retries recover the same saved page. The agent continues after your decision.
+Ask a Dot to show a draft before saving it. A CopilotKit human-in-the-loop card pauses the conversation for **Approve & save** or **Decline**. Approval creates the page in an authorized Space and returns a link; retries with the same draft recover that saved page. A changed draft needs a new review. The agent continues after your decision.
 
 ### Text and calls
 
diff --git a/src/client/PageReviewCard.tsx b/src/client/PageReviewCard.tsx
index 9962ce4b..4bf2582c 100644
--- a/src/client/PageReviewCard.tsx
+++ b/src/client/PageReviewCard.tsx
@@ -2,14 +2,16 @@ import { useEffect, useRef, useState } from 'react';
 import { Check, FileText, ArrowUpRight } from 'lucide-react';
 import ReactMarkdown from 'react-markdown';
 import { pageReviewSchema } from '../shared/page-review';
-import { decidePageReview, restorePageReview } from './page-review-decision';
-import { computerToolResult } from './ComputerToolCard';
+import {
+  decidePageReview,
+  matchesReviewedDraft,
+  restorePageReview,
+} from './page-review-decision';
 import { openPageLink } from './page-navigation';
-import type { Page } from '../server/pages';
+import type { ReviewedPage } from '../server/pages';
 export function PageReviewCard({
   args,
   status,
-  result,
   respond,
   threadId,
   toolCallId,
@@ -24,25 +26,21 @@ export function PageReviewCard({
   onSaved: () => void;
 }) {
   const draft = pageReviewSchema.safeParse(args);
-  const outcome = computerToolResult(result);
-  const [savedPage, setSavedPage] = useState<Page>();
+  const [savedPage, setSavedPage] = useState<ReviewedPage>();
   const [error, setError] = useState('');
   const [busy, setBusy] = useState(false);
   const [receiptReady, setReceiptReady] = useState(false);
   const [restoreAttempt, setRestoreAttempt] = useState(0);
   const pending = useRef(false);
   const finished = status === 'complete';
-  const recordedApproval = outcome.approved === true;
-  const saved = !!savedPage || recordedApproval;
-  const pageId =
-    savedPage?.id ?? (typeof outcome.pageId === 'string' ? outcome.pageId : '');
-  const spaceId =
-    savedPage?.spaceId ??
-    (typeof outcome.spaceId === 'string' ? outcome.spaceId : '');
+  const conflict = !!savedPage && !matchesReviewedDraft(savedPage, args);
+  const saved = !!savedPage && !conflict;
+  const pageId = savedPage?.id ?? '';
+  const spaceId = savedPage?.spaceId ?? '';
   useEffect(() => {
-    if (recordedApproval) return;
     let active = true;
     setReceiptReady(false);
+    setSavedPage(undefined);
     setError('');
     void restorePageReview(threadId, toolCallId)
       .then((page) => {
@@ -61,9 +59,9 @@ export function PageReviewCard({
     return () => {
       active = false;
     };
-  }, [threadId, toolCallId, recordedApproval, restoreAttempt]);
+  }, [threadId, toolCallId, restoreAttempt]);
   const decide = async (approved: boolean) => {
-    if (!respond || !receiptReady || pending.current) return;
+    if (!respond || !receiptReady || conflict || pending.current) return;
     pending.current = true;
     setBusy(true);
     setError('');
@@ -101,22 +99,26 @@ export function PageReviewCard({
       <header>
         <FileText size={17} />
         <strong>
-          {saved
-            ? 'Saved to your Space'
-            : !receiptReady
-              ? 'Checking saved review…'
-              : finished
-                ? 'Review ended'
-                : 'Ready for your review'}
+          {conflict
+            ? 'Review changed'
+            : saved
+              ? 'Saved to your Space'
+              : !receiptReady
+                ? 'Checking saved review…'
+                : finished
+                  ? 'Review ended'
+                  : 'Ready for your review'}
         </strong>
         <span>
-          {saved
-            ? 'Approved'
-            : !receiptReady
-              ? 'Checking'
-              : finished
-                ? 'Not saved'
-                : 'You decide'}
+          {conflict
+            ? 'Needs new review'
+            : saved
+              ? 'Approved'
+              : !receiptReady
+                ? 'Checking'
+                : finished
+                  ? 'Not saved'
+                  : 'You decide'}
         </span>
       </header>
       <div className="page-review-body">
@@ -136,6 +138,12 @@ export function PageReviewCard({
           </ReactMarkdown>
         )}
       </div>
+      {conflict && (
+        <p role="alert">
+          This review was saved with a different draft. Start a new review for
+          the changed draft.
+        </p>
+      )}
       {error && <p role="alert">{error}</p>}
       {!receiptReady && error && (
         <button
@@ -146,7 +154,7 @@ export function PageReviewCard({
         </button>
       )}
       <footer>
-        {saved && pageId && spaceId && (
+        {(saved || conflict) && pageId && spaceId && (
           <button
             type="button"
             className="review-primary"
@@ -156,10 +164,11 @@ export function PageReviewCard({
               )
             }
           >
-            Open page <ArrowUpRight size={15} />
+            {conflict ? 'Open saved page' : 'Open page'}{' '}
+            <ArrowUpRight size={15} />
           </button>
         )}
-        {!finished && respond && receiptReady && (
+        {!finished && respond && receiptReady && !conflict && (
           <>
             <button
               type="button"
@@ -185,7 +194,7 @@ export function PageReviewCard({
             )}
           </>
         )}
-        {!saved && (
+        {!saved && !conflict && (
           <small>
             {!receiptReady
               ? 'Checking whether this draft was already saved.'
diff --git a/src/client/page-review-decision.ts b/src/client/page-review-decision.ts
index 754db423..af32cb3e 100644
--- a/src/client/page-review-decision.ts
+++ b/src/client/page-review-decision.ts
@@ -1,26 +1,47 @@
 import { pageReviewSchema } from '../shared/page-review';
-import type { Page } from '../server/pages';
+import type { ReviewedPage } from '../server/pages';
 import { api } from './api';
 
 const reviewPath = (threadId: string) =>
   `/conversations/${encodeURIComponent(threadId)}/reviewed-page`;
 
 export function restorePageReview(threadId: string, toolCallId: string) {
-  return api<Page | null>(
+  return api<ReviewedPage | null>(
     `${reviewPath(threadId)}/${encodeURIComponent(toolCallId)}`,
   );
 }
 
+export function matchesReviewedDraft(page: ReviewedPage, args: unknown) {
+  // Receipts created before draft binding have no original snapshot.
+  if (!page.reviewDraft) return true;
+  const draft = pageReviewSchema.safeParse(args);
+  return (
+    draft.success &&
+    draft.data.title === page.reviewDraft.title &&
+    draft.data.content === page.reviewDraft.content &&
+    draft.data.spaceId === page.reviewDraft.spaceId
+  );
+}
+
 export async function decidePageReview(
   threadId: string,
   toolCallId: string,
   args: unknown,
   approved: boolean,
-): Promise<Page | null> {
+): Promise<ReviewedPage | null> {
   // A previous save may have committed even if its response never arrived.
   const previous = await restorePageReview(threadId, toolCallId);
-  if (previous) return previous;
+  if (previous) {
+    if (!matchesReviewedDraft(previous, args))
+      throw new Error(
+        'This review was saved with a different draft. Start a new review for the changed draft.',
+      );
+    return previous;
+  }
   if (!approved) return null;
   const draft = pageReviewSchema.parse(args);
-  return api<Page>(reviewPath(threadId), 'POST', { ...draft, toolCallId });
+  return api<ReviewedPage>(reviewPath(threadId), 'POST', {
+    ...draft,
+    toolCallId,
+  });
 }
diff --git a/src/server/page-routes.ts b/src/server/page-routes.ts
index c4963672..4b4bb145 100644
--- a/src/server/page-routes.ts
+++ b/src/server/page-routes.ts
@@ -17,9 +17,10 @@ export function pageRoutes(platform: Platform) {
         { error: 'This Dot no longer has access to the selected Space.' },
         403,
       );
-    return c.json(
-      platform.workspace.pages.get(receipt.spaceId, receipt.pageId),
-    );
+    return c.json({
+      ...platform.workspace.pages.get(receipt.spaceId, receipt.pageId),
+      reviewDraft: receipt.draft,
+    });
   });
   app.post('/conversations/:id/reviewed-page', async (c) => {
     const data = pageReviewSchema
diff --git a/src/server/pages.ts b/src/server/pages.ts
index 128f756a..ebe04642 100644
--- a/src/server/pages.ts
+++ b/src/server/pages.ts
@@ -1,6 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import type { DatabaseSync } from 'node:sqlite';
 import { z } from 'zod';
+import {
+  pageReviewSchema,
+  type PageReviewDraft,
+} from '../shared/page-review.js';
 export const pageInput = z
   .object({
     title: z.string().trim().min(1).max(160),
@@ -27,6 +31,9 @@ export interface Page {
   updatedAt: number;
   sourceThreadId: string | null;
 }
+export type ReviewedPage = Page & {
+  reviewDraft: PageReviewDraft | null;
+};
 export class PageError extends Error {
   constructor(
     message: string,
@@ -41,8 +48,15 @@ export class Pages {
     private spaceExists: (id: string) => boolean,
   ) {
     db.exec(
-      'CREATE TABLE IF NOT EXISTS page_reviews(threadId TEXT NOT NULL, toolCallId TEXT NOT NULL, pageId TEXT NOT NULL, spaceId TEXT NOT NULL, PRIMARY KEY(threadId,toolCallId))',
+      'CREATE TABLE IF NOT EXISTS page_reviews(threadId TEXT NOT NULL, toolCallId TEXT NOT NULL, pageId TEXT NOT NULL, spaceId TEXT NOT NULL, draft TEXT, PRIMARY KEY(threadId,toolCallId))',
     );
+    if (
+      !db
+        .prepare('PRAGMA table_info(page_reviews)')
+        .all()
+        .some((row) => row.name === 'draft')
+    )
+      db.exec('ALTER TABLE page_reviews ADD COLUMN draft TEXT');
     db.exec(`CREATE TABLE IF NOT EXISTS pages(id TEXT PRIMARY KEY, spaceId TEXT NOT NULL, parentId TEXT, title TEXT NOT NULL, content TEXT NOT NULL, revision INTEGER NOT NULL, createdAt INTEGER NOT NULL, updatedAt INTEGER NOT NULL, sourceThreadId TEXT);
  CREATE TABLE IF NOT EXISTS page_threads(pageId TEXT NOT NULL,dotId TEXT NOT NULL,threadId TEXT NOT NULL UNIQUE,ready INTEGER NOT NULL DEFAULT 0, leaseUntil INTEGER NOT NULL DEFAULT 0, PRIMARY KEY(pageId,dotId));`);
     if (
@@ -117,45 +131,63 @@ export class Pages {
   reviewReceipt(
     threadId: string,
     toolCallId: string,
-  ): { pageId: string; spaceId: string } | null {
+  ): { pageId: string; spaceId: string; draft: PageReviewDraft | null } | null {
     const row = this.db
       .prepare(
-        'SELECT pageId,spaceId FROM page_reviews WHERE threadId=? AND toolCallId=?',
+        'SELECT pageId,spaceId,draft FROM page_reviews WHERE threadId=? AND toolCallId=?',
       )
       .get(threadId, toolCallId);
     return row
-      ? { pageId: String(row.pageId), spaceId: String(row.spaceId) }
+      ? {
+          pageId: String(row.pageId),
+          spaceId: String(row.spaceId),
+          draft: row.draft
+            ? pageReviewSchema.parse(JSON.parse(String(row.draft)))
+            : null,
+        }
       : null;
   }
   createReviewed(
     spaceId: string,
-    input: z.input<typeof pageInput>,
+    input: Pick<PageReviewDraft, 'title' | 'content'>,
     threadId: string,
     toolCallId: string,
-  ): Page {
+  ): ReviewedPage {
+    const draft = pageReviewSchema.parse({ ...input, spaceId });
     this.db.exec('BEGIN IMMEDIATE');
     try {
-      const previous = this.db
-        .prepare(
-          'SELECT pageId,spaceId FROM page_reviews WHERE threadId=? AND toolCallId=?',
-        )
-        .get(threadId, toolCallId);
+      const previous = this.reviewReceipt(threadId, toolCallId);
       if (previous) {
         if (previous.spaceId !== spaceId)
           throw new PageError(
             'This review was already saved to another Space.',
             409,
           );
-        const page = this.get(spaceId, String(previous.pageId));
+        if (
+          previous.draft &&
+          (previous.draft.title !== draft.title ||
+            previous.draft.content !== draft.content)
+        )
+          throw new PageError(
+            'This review was already saved with a different draft. Start a new review for the changed draft.',
+            409,
+          );
+        const page = this.get(spaceId, previous.pageId);
         this.db.exec('COMMIT');
-        return page;
+        return { ...page, reviewDraft: previous.draft };
       }
-      const page = this.create(spaceId, input, threadId);
+      const page = this.create(
+        spaceId,
+        { title: draft.title, content: draft.content },
+        threadId,
+      );
       this.db
-        .prepare('INSERT INTO page_reviews VALUES (?,?,?,?)')
-        .run(threadId, toolCallId, page.id, spaceId);
+        .prepare(
+          'INSERT INTO page_reviews (threadId,toolCallId,pageId,spaceId,draft) VALUES (?,?,?,?,?)',
+        )
+        .run(threadId, toolCallId, page.id, spaceId, JSON.stringify(draft));
       this.db.exec('COMMIT');
-      return page;
+      return { ...page, reviewDraft: draft };
     } catch (error) {
       this.db.exec('ROLLBACK');
       throw error;
diff --git a/src/shared/page-review.ts b/src/shared/page-review.ts
index 1ba7f6a3..c33f5094 100644
--- a/src/shared/page-review.ts
+++ b/src/shared/page-review.ts
@@ -6,6 +6,7 @@ export const pageReviewSchema = z
     spaceId: z.string().min(1),
   })
   .strict();
+export type PageReviewDraft = z.infer<typeof pageReviewSchema>;
 export const pageReviewTool = {
   name: 'review_space_page',
   description:
diff --git a/tests/page-review.test.tsx b/tests/page-review.test.tsx
index 011791f9..3d6728e6 100644
--- a/tests/page-review.test.tsx
+++ b/tests/page-review.test.tsx
@@ -35,7 +35,7 @@ it('does not decide or save when receipt recovery fails', async () => {
 
 it('checks for a receipt before retrying a save whose response was lost', async () => {
   const draft = { title: 'Brief', content: 'Evidence', spaceId: 'space' };
-  const page = { id: 'saved', ...draft };
+  const page = { id: 'saved', ...draft, reviewDraft: draft };
   vi.mocked(api)
     .mockResolvedValueOnce(null)
     .mockRejectedValueOnce(new Error('Connection lost'));
@@ -49,6 +49,36 @@ it('checks for a receipt before retrying a save whose response was lost', async
   ).toHaveLength(1);
 });
 
+it('rejects a changed restored draft before sending a decision or another save', async () => {
+  const original = {
+    title: 'Brief',
+    content: 'Approved text',
+    spaceId: 'space',
+  };
+  const page = {
+    id: 'saved',
+    ...original,
+    content: 'The page was edited later.',
+    reviewDraft: original,
+  };
+  vi.mocked(api).mockResolvedValue(page);
+  expect(
+    await decidePageReview('thread', 'call', original, true),
+  ).toMatchObject({ id: 'saved' });
+  for (const changed of [
+    { ...original, title: 'Changed' },
+    { ...original, content: 'Changed' },
+    { ...original, spaceId: 'other' },
+  ]) {
+    await expect(
+      decidePageReview('thread', 'call', changed, true),
+    ).rejects.toThrow('different draft');
+  }
+  expect(
+    vi.mocked(api).mock.calls.filter((call) => call[1] === 'POST'),
+  ).toHaveLength(0);
+});
+
 it('hides decisions and unsaved claims until the persisted receipt is checked', () => {
   const html = renderToStaticMarkup(
     <PageReviewCard
diff --git a/tests/page-routes.test.ts b/tests/page-routes.test.ts
index 9b0f8fec..a14d023f 100644
--- a/tests/page-routes.test.ts
+++ b/tests/page-routes.test.ts
@@ -175,7 +175,54 @@ it('saves reviewed drafts once and rechecks the Dot’s Space access', async ()
   const saved = await first.json();
   const retry = await app.request(path, request(draft));
   expect((await retry.json()).id).toBe(saved.id);
+  expect(
+    (await app.request(path, request({ ...draft, title: '  Launch brief  ' })))
+      .status,
+  ).toBe(201);
+  expect(saved.reviewDraft).toEqual({
+    title: draft.title,
+    content: draft.content,
+    spaceId: dot.spaceId,
+  });
+  for (const changed of [
+    { ...draft, title: 'Different title' },
+    { ...draft, content: 'Different content.' },
+  ]) {
+    const conflict = await app.request(path, request(changed));
+    expect(conflict.status).toBe(409);
+    expect(await conflict.json()).toMatchObject({
+      error: expect.stringContaining('different draft'),
+    });
+  }
   expect(ws.pages.list(dot.spaceId)).toHaveLength(1);
+  ws.pages.update(dot.spaceId, saved.id, {
+    expectedRevision: 1,
+    content: 'The saved page was edited later.',
+  });
+  const restored = await app.request(`${path}/review-1`);
+  expect(await restored.json()).toMatchObject({
+    content: 'The saved page was edited later.',
+    reviewDraft: {
+      title: draft.title,
+      content: draft.content,
+      spaceId: dot.spaceId,
+    },
+  });
+  const retryAfterEdit = await app.request(path, request(draft));
+  expect((await retryAfterEdit.json()).id).toBe(saved.id);
+  const authorizedOther = ws.createSpace('Authorized other', '');
+  ws.updateDot(dot.id, {
+    ...dot,
+    spaceIds: [dot.spaceId, authorizedOther.id],
+  });
+  expect(
+    (
+      await app.request(
+        path,
+        request({ ...draft, spaceId: authorizedOther.id }),
+      )
+    ).status,
+  ).toBe(409);
   const other = ws.createSpace('Other', '');
   ws.updateDot(dot.id, { ...dot, spaceId: other.id, spaceIds: [other.id] });
   expect((await app.request(path, request(draft))).status).toBe(403);
diff --git a/tests/pages.test.ts b/tests/pages.test.ts
index 4dd83d2c..fd2b9707 100644
--- a/tests/pages.test.ts
+++ b/tests/pages.test.ts
@@ -2,6 +2,7 @@ import { expect, it } from 'vitest';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
 import { WorkspaceStore } from '../src/server/workspace.js';
 it('persists nested page content and revision across restart', () => {
   const dir = mkdtempSync(join(tmpdir(), 'dots-pages-'));
@@ -51,3 +52,59 @@ it('rejects cross-space parents, cycles and stale writes without losing content'
   expect(() => store.pages.get(b, root.id)).toThrow();
   store.close();
 });
+it('migrates review receipts and retains their original draft after restart', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'dots-reviews-'));
+  const path = join(dir, 'db');
+  const legacy = new DatabaseSync(path);
+  legacy.exec(
+    'CREATE TABLE page_reviews(threadId TEXT NOT NULL, toolCallId TEXT NOT NULL, pageId TEXT NOT NULL, spaceId TEXT NOT NULL, PRIMARY KEY(threadId,toolCallId))',
+  );
+  legacy.close();
+  let store = new WorkspaceStore(path, 'owner');
+  const space = store.spaces()[0].id;
+  store.pages.createReviewed(
+    space,
+    { title: 'Original', content: 'Reviewed content' },
+    'thread',
+    'call',
+  );
+  const olderPage = store.pages.create(space, {
+    title: 'Earlier approval',
+    content: 'Earlier draft',
+  });
+  store.close();
+  const oldReceipt = new DatabaseSync(path);
+  oldReceipt
+    .prepare(
+      'INSERT INTO page_reviews (threadId,toolCallId,pageId,spaceId) VALUES (?,?,?,?)',
+    )
+    .run('earlier-thread', 'earlier-call', olderPage.id, space);
+  oldReceipt.close();
+  store = new WorkspaceStore(path, 'owner');
+  expect(store.pages.reviewReceipt('thread', 'call')?.draft).toMatchObject({
+    title: 'Original',
+    content: 'Reviewed content',
+    spaceId: space,
+  });
+  expect(() =>
+    store.pages.createReviewed(
+      space,
+      { title: 'Changed', content: 'Reviewed content' },
+      'thread',
+      'call',
+    ),
+  ).toThrow('different draft');
+  expect(
+    store.pages.reviewReceipt('earlier-thread', 'earlier-call')?.draft,
+  ).toBeNull();
+  expect(
+    store.pages.createReviewed(
+      space,
+      { title: 'Earlier approval', content: 'Earlier draft' },
+      'earlier-thread',
+      'earlier-call',
+    ).id,
+  ).toBe(olderPage.id);
+  store.close();
+  rmSync(dir, { recursive: true });
+});