Skip to content

Save plan review's linked-document comments per document (#1545) - #2263

Merged
backnotprop merged 11 commits into
mainfrom
fix/plan-linked-doc-drafts
Oct 28, 2026
Merged

backnotprop merged 11 commits into
mainfrom
fix/plan-linked-doc-drafts

Conversation

@backnotprop

@backnotprop backnotprop commented Oct 27, 2026 •

Copy link
Copy Markdown
Owner

Fixes #1545 (plan review with linked docs)

Problem

In plan review, and in annotate sessions with no file of their own (a URL or the last message), the draft held only the document that was open:

  • Opening a linked document with no comments emptied the draft, and the client deleted it. A reload then lost every comment.
  • A reload while a linked document was open offered that document's comments in Draft Recovered, and put them on the plan as Unanchored cards.

#1710 fixed this for annotate on files and folders by saving each document under its own path (/api/draft/document). This PR gives plan review, and the URL and last-message annotate sessions, the same per-document saving, through the same shared code. It changes both runtimes.

What changes

Shared (packages/shared/annotate-draft.ts, vendored to Pi)

  • The per-document copy logic moves out of createAnnotateDraftSession into createDocumentDraftStore. Annotate file and folder sessions behave as before. The existing Annotate drafts follow the file's path (0.29 PR 2) #1710 scenarios pass on both runtimes. One was rewritten on purpose: "a URL session has neither a path copy nor document copies" became "a URL session has no path copy, but its linked documents get copies", because URL sessions now get document copies (this PR's change). Every other Annotate drafts follow the file's path (0.29 PR 2) #1710 scenario is unchanged.
  • New option indexKey: a session whose root has no file keeps a durable list of the copies it wrote or read (documentDraftIndexKey(<session draft key>)).
  • loadSessionDraftWithDocuments: GET /api/draft adds documents: [{ path, annotations, globalAttachments }] for every listed copy. If only linked documents have comments, it returns a draft with no root comments. That draft carries the session key's generation, so the client resumes above a tombstone.
  • A decision clears every copy the session wrote, read or lists. After that, document writes get 409.
  • The index key comes from the root's text alone, so the same plan (or message, or page) in two working folders (worktrees) shares one index. A session offers, counts and clears only the entries it can serve (an existing file at that canonical path, allowed by isAllowed, not the session's own file). On a decision it drops its own entries and keeps the others; the index file is deleted only when it ends up empty.
  • doc-resolve.ts: isPlanLinkedDocPath, so the Bun plan server accepts exactly the documents /api/doc serves beside the plan file.

Bun (packages/server/index.ts, packages/server/annotate.ts)

  • The plan server creates a document store (not in archive mode) and serves /api/draft/document.
  • /api/plan advertises documentDrafts: true.
  • GET /api/draft offers documents. POST and DELETE of /api/draft are unchanged, so a single-document plan's draft is served exactly as before.
  • Approve and deny clear the copies. The host status unsentAnnotations counts them.
  • Allowed paths: inside the project, or a file the plan links beside its plan file.
  • Annotate: URL and annotate-last sessions get per-document copies with the index (annotateSessionHasRootlessDocuments).
  • GET /api/draft/document marks the copy it reads as the session's (and lists it in the index), so a decision clears it. It now has the same cross-site guard as the writes (isSameOriginOrNoOrigin, 403), on the plan and annotate servers.

Pi (apps/pi-extension/server/serverPlan.ts, serverAnnotate.ts)

  • Same as Bun: the store, /api/draft/document (with the cross-site guard on GET), the advert, GET /api/draft with documents, and clearing on approve and deny.
  • The session close keeps the copies, the same as it keeps the plan's draft. unsentAnnotations counts them on status and close.
  • Allowed paths: inside the project. Pi's /api/doc serves nothing beside the plan file.
  • Annotate: same as Bun.

Client

  • useAnnotationDraft (@plannotator/ui, additive):
    • It parses documents, and the banner count includes them.
    • draftBanner.documents and draftBanner.documentComments (how many of count are on other documents) are set only when there are other documents, so a root-only banner is byte-identical to before.
    • restoreDraft() returns documents. dismissDraft() returns the documents it discarded.
  • useLinkedDoc.restoreStoredDocuments puts restored comments on their own documents before those documents are opened, so they count, list and reach the feedback at once.
  • App wires the restore and dismiss paths:
    • Restore puts each document's comments on that document and marks its copy as read (adoptRestoredCopies), so it is not merged a second time.
    • Dismiss clears the documents' copies (discardCopies).
    • The banner reads "Found 2 annotations (including comments on 1 linked document)". When the plan itself has no comments, it reads "Found 1 annotation on 1 linked document".
  • The plan's own draft keeps the plan's comments while a linked document is open (Annotate drafts follow the file's path (0.29 PR 2) #1710's composeSessionDraft, now on for plan review). Opening an empty linked document therefore never empties or deletes it.

Docs: a new "Linked documents in plan review" section in plan-review.md, the session scope in annotate.md, and the API table rows in server-and-storage.md.

Tests (fail on main, pass here)

  • Server, both runtimes: packages/server/linked-document-drafts.scenarios.ts, run by packages/server/linked-document-drafts.test.ts (Bun) and apps/pi-extension/server/linked-document-drafts.test.ts (Pi).
    • Scenarios: the advert; reload and reopen offer every document; the plan draft going empty keeps the linked document's comments; a document read back is offered later; approve and deny each clear everything and refuse writes; a path outside the project is refused; the last-message session works the same way.
    • Two working folders: for plan (approve, deny), last-message (approve, feedback) and URL (approve, feedback), folder A comments on its design document and leaves undecided; folder B with the same text is not offered A's copy, counts only its own (unsentAnnotations 1), decides, and clears its own copy; back in A, A's comment is still offered.
    • A cross-site GET of a copy (plan, last-message, URL) gets 403 and does not list the copy.
    • Bun only (planFileDocuments): a plan file in a plans/ folder outside the project. The linked beside.md is accepted; an unlinked sibling plan, a linked symlink that points outside, a plans/../outside.md traversal, a linked ../outside.md and a relative path are refused (rejected on POST; 403, or 400 for the relative path, on GET).
    • 39 scenarios in all (Bun 20, Pi 19).
  • Hook (DOM): packages/ui/hooks/useAnnotationDraft.documents.test.tsx.
    • Covers: the banner count, restore attribution, a draft with only linked-document comments, and dismiss returning the documents.
    • On main, 3 of 4 fail. The 4th guards the unchanged root-only banner.
  • App (DOM): packages/editor/App.planLinkedDrafts.test.tsx.
    • Covers: Draft Recovered offers and restores the design document's comment on that document, with no second merge and no write-back; a draft with comments only on a linked document does not say "including"; opening an empty linked document never deletes the plan's draft; Dismiss clears the copies.
    • On main, 2 of 3 fail. The empty-document guard passes on main here because the fake server advertises copies; the e2e below shows the real failure.
  • E2E: tests/e2e/plan-linked-doc-drafts.spec.ts (headless Chromium, compiled binary, temp data dir and HOME, NO_BROWSER).
    • Steps: comment on the plan and on a linked document, open an empty linked document, reload. Draft Recovered offers both comments; Restore puts each on its document. Send Feedback prints the plan's comment before "Linked Document Feedback" and the design document's comment under design.md.
    • With a binary built from main, it fails at "Draft Recovered" not shown, because the draft was deleted.
  • CI: inbox-e2e.yml now also runs when packages/editor/**, packages/server/index.ts, packages/server/annotate.ts, packages/shared/annotate*, draft.ts, review-draft.ts or doc-resolve.ts change, so a regression in App, the plan or annotate server, or the shared draft store runs plan-linked-doc-drafts.spec.ts and the annotate-* specs. The Pi server files are not listed: those specs drive only the compiled Bun binary, and test.yml (bun test) runs the Pi mirrors of the scenarios.
  • Also run:
    • After merging main (the new Inbox announcement), the DOM test and the e2e seed plannotator-announce-inbox-seen, as main's other specs do; everything below was rerun on the merged tree except the broad bun test run.
    • bun run typecheck; built in order (review, then hook, then opencode) and compiled .local/plannotator with the CI flags.
    • E2E, headless Chromium: plan-linked-doc-drafts and the annotate-* specs, --repeat-each 2: 28/28 pass.
    • DOM (DOM_TESTS=1): App.planLinkedDrafts, useAnnotationDraft.documents, App.documentDrafts, useAnnotationDraft.seam, annotationDraftStaleRetry: 18/18 pass.
    • bun test packages/server packages/shared apps/pi-extension packages/editor packages/ui tests/agents-md-size.test.ts scripts/dom-test-allowlist.test.ts tests/no-browser-sentinel.test.ts: 6808 pass, 4 fail. The 4 are in apps/pi-extension/inbox.test.ts (the real Pi in RPC mode against an Inbox), timing under the full run's load; that file passes alone (13/13). None is in draft code.
    • All runs used a temp HOME and PLANNOTATOR_DATA_DIR, PLANNOTATOR_INBOX_CONNECT=0, the no-browser value, and stub agent CLIs first on PATH.
  • Mutation checks (each reverted after): dropping the servable filter from countUnsent or from settle, or deleting the index file on every decision, fails the 12 two-folder scenarios (6 per runtime). Removing settle() from /api/approve fails the approve scenarios on that runtime. Removing the Bun plan-file allowance, accepting the whole plan folder, or a lexical (non-realpath) containment check in resolvePlanLinkedDoc fails the plan-file scenario. Removing the GET guard fails the cross-site scenario for that server (plan, or last-message and URL), on each runtime. Always saying "including" fails the new App DOM test.

Notes for review

  • Copies follow the file, as in Annotate drafts follow the file's path (0.29 PR 2) #1710. An abandoned plan review's comments on docs/design.md also come back, with the existing toast, when that file is opened in another session.
  • Live-app sessions still have no document copies. Their draft keeps the old behavior: it holds the open document only.

… the draft GET (#1545 review)

- Shared store: settle() and countUnsent() act only on index entries this
  session can serve (offered()'s check). A decision drops the session's own
  entries and keeps the rest; the index file is deleted only when empty.
  The same plan, message or page in two working folders no longer lets one
  decision delete the other folder's unsent comments.
- GET /api/draft/document marks the copy as the session's, so it gets the
  writes' cross-site guard on the Bun and Pi plan and annotate servers.
- Banner: 'Found 1 annotation on 1 linked document' when the root has none.
- Scenarios (both runtimes): approve clears; two working folders for plan,
  last-message and URL sessions; cross-site GET refused. Bun only: the plan
  file allowance (linked file accepted; unlinked sibling, symlink out,
  traversal, relative refused).
- inbox-e2e.yml runs on editor, plan/annotate server and draft store changes.
…-drafts

# Conflicts:
#	tests/e2e/playwright.config.ts
…y per line)

# Conflicts:
#	tests/e2e/playwright.config.ts
@backnotprop
backnotprop merged commit a565e5a into main Oct 28, 2026
30 checks passed
backnotprop pushed a commit that referenced this pull request Oct 31, 2026
… send clears only what that page saw

- Every annotate session with per-document copies (a file, a folder, a
  bundle) now keeps the index #2263 gave plan review and URL / last-message
  sessions, so GET /api/draft offers every document's comments after a
  reload instead of only when each document is opened again.
- The store remembers which copies each page (`?client=` page id) read,
  wrote or restored. A decision that names a page clears only those, so a
  reloaded or crashed tab's copies the new page never saw survive its send.
  A caller without a page id clears what this server wrote, read or offered,
  and no longer every copy the index lists.
- Both runtimes (Bun and Pi) pass the page id on /api/draft/document and on
  every decision route, plan review's included.
- Scenarios, both runtimes: the reported loss (three files, reload, open one,
  send), a page that restores everything and sends, a second tab's decision,
  Close from a reloaded page, and a single-file session's linked document.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Annotation draft only persists the open document; other documents' comments are lost on reload in folder and linked-doc sessions

1 participant