@cueloop/client 0.1.0-alpha.23 → 0.1.0-alpha.26

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.26",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@cueloop/daemon": "0.1.0-alpha.23",
-    "@cueloop/extension-api": "0.1.0-alpha.23",
-    "@cueloop/integration-obsidian": "0.1.0-alpha.23",
-    "@cueloop/schema": "0.1.0-alpha.23",
+    "@cueloop/daemon": "0.1.0-alpha.26",
+    "@cueloop/extension-api": "0.1.0-alpha.26",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.26",
+    "@cueloop/schema": "0.1.0-alpha.26",
     "@opentui/core": "^0.5.1",
     "@opentui/keymap": "0.5.1",
     "@opentui/react": "^0.5.1",

package/src/App.diff.test.tsx

@@ -69,7 +69,7 @@ describe("diff review", () => {
     await press(setup, "c");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("COMMENT ON");
+    await waitForText(setup, "COMMENT ON");
 
     // Act
     await setup.mockInput.typeText("Map needs an eviction story.");
@@ -101,6 +101,6 @@ describe("diff review", () => {
     await press(setup, "x");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("plan-only verb");
+    await waitForText(setup, "plan-only verb");
   });
 });

package/src/App.export.test.tsx

@@ -54,7 +54,7 @@ describe("obsidian export on resolve", () => {
     await press(setup, "enter"); // open the submit overlay, keep the default verdict (approve)
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("verdict");
+    await waitForText(setup, "verdict");
 
     // Act
     await press(setup, "enter"); // submit

package/src/App.plan-review.test.tsx

@@ -76,12 +76,38 @@ async function toContextParagraph(setup: Setup): Promise<void> {
 }
 
 describe("share button", () => {
-  test("the owner's rail shows the one-click Share button", async () => {
+  test("the owner's plan header shows the Share button next to Edit", async () => {
     // Arrange / Act
     const setup = await renderApp();
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("Share plan");
+    // both word-buttons ride the same header row, so Share sits next to Edit
+    const headerLine = setup.captureCharFrame().split("\n").find((line) => line.includes("submitted by"));
+    expect(headerLine).toContain("Edit");
+    expect(headerLine).toContain("Share");
+  });
+
+  test("a read-only viewer (a plan shared over ssh) never sees the Share button", async () => {
+    // Arrange / Act
+    const viewer = await testRender(<App home={home} sessionId={session.id} readOnly />, { width: 120, height: 32 });
+    await waitForText(viewer, "cueloop");
+
+    // Assert
+    expect(viewer.captureCharFrame()).not.toContain("Share");
+  });
+
+  test("a resolved plan hides Edit and Share (no re-sharing a finished review)", async () => {
+    // Arrange - resolve the session before opening it
+    server.core.sessionResolve(session.id, "approve", "");
+
+    // Act
+    const setup = await renderApp();
+    await waitForText(setup, "submitted by");
+
+    // Assert - the owner toolbar is gone once the review is resolved
+    const headerLine = setup.captureCharFrame().split("\n").find((line) => line.includes("submitted by"));
+    expect(headerLine).not.toContain("Edit");
+    expect(headerLine).not.toContain("Share");
   });
 });
 
@@ -116,7 +142,7 @@ describe("selection feeds the annotation quote", () => {
     await press(setup, "c");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain('comment on "The daemon"');
+    await waitForText(setup, 'comment on "The daemon"');
 
     // Act
     await type(setup, "Which daemon?");
@@ -143,7 +169,7 @@ describe("selection feeds the annotation quote", () => {
     await press(setup, "c");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain('comment on "persists sessions"');
+    await waitForText(setup, 'comment on "persists sessions"');
 
     // Act
     await type(setup, "sessions plural?");
@@ -170,7 +196,7 @@ describe("inline compose keeps the anchor painted", () => {
     // Assert
     // compose open: the anchor is painted selection-style. The box can render
     // a frame before the anchor repaint settles, so wait on the color itself.
-    expect(setup.captureCharFrame()).toContain("Save ⏎");
+    await waitForText(setup, "Save ⏎");
     expect(setup.captureCharFrame()).toContain("Cancel esc");
     await waitForState(setup, () => backgroundsOf(setup, "The daemon").includes(T.accent));
     expect(backgroundsOf(setup, "The daemon")).toContain(T.accent);
@@ -197,8 +223,9 @@ describe("inline compose keeps the anchor painted", () => {
     expect(stored.annotations.length).toBe(1);
     expect(backgroundsOf(setup, stored.annotations[0]!.anchor.quote.slice(0, 20))).toContain(T.markCommentBg);
     // renderApp plus this many frame-waits grazes the 5s default on a loaded CI
-    // runner; the sibling walk resume test carries the same budget.
-  }, 15_000);
+    // runner, and the whole-suite publish lane has timed even 15s out; give the
+    // heaviest frame-wait chain generous headroom so runner load cannot flake it.
+  }, 30_000);
 });
 
 describe("compose newline convention", () => {
@@ -363,7 +390,7 @@ describe("addressed annotations leave the open list", () => {
 });
 
 describe("sheet header", () => {
-  test("shows the submitting agent, the revision, and the Edit word-button", async () => {
+  test("shows the submitting agent, the revision, and the Edit and Share word-buttons", async () => {
     // Arrange
     const setup = await renderApp();
 
@@ -371,6 +398,7 @@ describe("sheet header", () => {
     const frame = setup.captureCharFrame();
     expect(frame).toContain("submitted by agent/worker-3 · revision 1");
     expect(frame).toContain("Edit");
+    expect(frame).toContain("Share");
   });
 
   test("the Agent tab shows the submitter, status, and revision", async () => {
@@ -385,6 +413,7 @@ describe("sheet header", () => {
     await setup.renderOnce();
 
     // Assert
+    await waitForText(setup, "status: pending");
     const frame = setup.captureCharFrame();
     expect(frame).toContain("agent/worker-3");
     expect(frame).toContain("status: pending");

package/src/App.readonly.test.tsx

@@ -142,6 +142,6 @@ describe("observer navigation still works", () => {
     await setup.renderOnce();
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("▸ COMMENT");
+    await waitForText(setup, "▸ COMMENT");
   });
 });

package/src/App.review-panel.test.tsx

@@ -10,7 +10,7 @@ import { DaemonServer } from "@cueloop/daemon";
 import type { ReviewSession } from "@cueloop/schema";
 import { App } from "./App";
 import { loadConfig } from "./config";
-import { press, waitForText } from "./test-support";
+import { press, waitForText, waitForTextGone } from "./test-support";
 
 const PLAN = "# Plan\n\nShip the thing.\n";
 
@@ -54,6 +54,7 @@ describe("review panel", () => {
     await press(setup, "b");
 
     // Assert
+    await waitForText(setup, "«");
     let frame = setup.captureCharFrame();
     expect(frame).toContain("«"); // compact strip shows the expand chevron
     expect(frame).not.toContain("Submit review");
@@ -62,7 +63,7 @@ describe("review panel", () => {
     await press(setup, "b");
 
     // Assert
-    frame = setup.captureCharFrame();
+    frame = await waitForTextGone(setup, "«");
     expect(frame).not.toContain("«"); // hidden: no strip, no divider
     expect(frame).not.toContain("│");
 
@@ -70,7 +71,7 @@ describe("review panel", () => {
     await press(setup, "b");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("Submit review"); // back to expanded
+    await waitForText(setup, "Submit review"); // back to expanded
   });
 
   test("the collapse mode persists to the user config", async () => {
@@ -104,12 +105,14 @@ describe("review panel", () => {
     await press(setup, "b"); // -> hidden
 
     // Assert
-    expect(setup.captureCharFrame()).not.toContain("Submit review"); // rail is gone
+    await waitForTextGone(setup, "Submit review"); // rail is gone
+    expect(setup.captureCharFrame()).not.toContain("Submit review");
 
     // Act
     await press(setup, "enter"); // submit while hidden must not trap in an invisible modal
 
     // Assert
+    await waitForText(setup, "submit review");
     const frame = setup.captureCharFrame();
     expect(frame).toContain("submit review"); // the confirm card is visible again
     expect(frame).toContain("[Approve]");

package/src/App.submit-confirm.test.tsx

@@ -77,6 +77,7 @@ describe("rail submit confirm", () => {
     await press(setup, "enter");
 
     // Assert
+    await waitForText(setup, "submit review");
     const frame = setup.captureCharFrame();
     // the card: title, honest counts, verdict selector, word-buttons
     expect(frame).toContain("submit review");
@@ -96,25 +97,25 @@ describe("rail submit confirm", () => {
     await press(setup, "enter");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("[Approve]");
+    await waitForText(setup, "[Approve]");
 
     // Act
     await press(setup, "right");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("[Changes]");
+    await waitForText(setup, "[Changes]");
 
     // Act
     await press(setup, "right");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("[Comment]");
+    await waitForText(setup, "[Comment]");
 
     // Act
     await press(setup, "left");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("[Changes]");
+    await waitForText(setup, "[Changes]");
   });
 
   test("esc cancels the card and restores the plain Submit button", async () => {
@@ -123,7 +124,7 @@ describe("rail submit confirm", () => {
     await press(setup, "enter");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("[Approve]");
+    await waitForText(setup, "[Approve]");
 
     // Act
     await press(setup, "escape");
@@ -144,6 +145,7 @@ describe("rail submit confirm", () => {
     await press(setup, "enter");
 
     // Assert
+    await waitForText(setup, "1 annotations · 0 blocking");
     const frame = setup.captureCharFrame();
     expect(frame).toContain("1 annotations · 0 blocking");
     expect(frame).toContain("[Changes]"); // pending items: request changes default
@@ -170,19 +172,16 @@ describe("rail submit confirm", () => {
     for (let index = 0; index < 12; index++) await press(setup, "n");
 
     // Assert
-    const scrolled = setup.captureCharFrame();
-    expect(scrolled).toContain("note 12");
-    expect(scrolled).not.toContain("note 01");
+    await waitForText(setup, "note 12");
+    expect(setup.captureCharFrame()).not.toContain("note 01");
 
     // Act
     await press(setup, "enter");
 
     // Assert
-    const opened = setup.captureCharFrame();
-    // the card is pinned outside the scrollbox; the stack above stays
-    // scrolled away from the top when the card takes its space
-    expect(opened).toContain("12 annotations · 0 blocking");
-    expect(opened).not.toContain("note 01");
+    await waitForText(setup, "12 annotations · 0 blocking");
+    // the card is pinned outside the scrollbox; the stack stays scrolled off the top
+    expect(setup.captureCharFrame()).not.toContain("note 01");
 
     // Act
     // the stack still scrolls with the card open: wheel over the rail
@@ -191,8 +190,8 @@ describe("rail submit confirm", () => {
     await settle(setup);
 
     // Assert
+    await waitForText(setup, "note 12");
     const scrolledWithCard = setup.captureCharFrame();
-    expect(scrolledWithCard).toContain("note 12");
     expect(scrolledWithCard).toContain("12 annotations · 0 blocking");
     expect(scrolledWithCard).not.toContain("note 01");
   });
@@ -206,6 +205,7 @@ describe("rail submit confirm", () => {
     await press(setup, "enter");
 
     // Assert
+    await waitForText(setup, "observer - read-only");
     const frame = setup.captureCharFrame();
     expect(frame).toContain("observer - read-only");
     expect(frame).not.toContain("1 annotations");

package/src/App.test.tsx

@@ -94,7 +94,7 @@ describe("keyboard grammar", () => {
     await setup.renderOnce();
 
     // Assert
-    expect(setup.captureCharFrame()).toContain('comment on "The daemon');
+    await waitForText(setup, 'comment on "The daemon');
 
     // Act
     await type(setup, "Define atomically.");
@@ -182,7 +182,7 @@ describe("submit", () => {
     await press(setup, "enter"); // open submit
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("[Changes]");
+    await waitForText(setup, "[Changes]");
 
     // Act
     await type(setup, "Expand the steps.");
@@ -206,7 +206,7 @@ describe("submit", () => {
     await press(setup, "enter");
 
     // Assert
-    expect(setup.captureCharFrame()).toContain("[Approve]"); // no pending items → approve default
+    await waitForText(setup, "[Approve]"); // no pending items → approve default
 
     // Act
     await press(setup, "enter");

package/src/App.tsx

@@ -92,6 +92,12 @@ export function App({ home, sessionId, readOnly = false, onExit, clock, openClie
     controller.getSnapshot,
     controller.getSnapshot,
   );
+  // A shared plan you own polls for collaborator notes while it is open; the
+  // merge refreshes through the normal event path. Stops on leave.
+  useEffect(() => {
+    if (!isOwner || !session?.shareId) return;
+    return controller.startSharePoll();
+  }, [isOwner, session?.id, session?.shareId, controller]);
   const renderer = useRenderer();
   const { width: terminalWidth, height: terminalHeight } = useTerminalDimensions();
 
@@ -366,7 +372,7 @@ export function App({ home, sessionId, readOnly = false, onExit, clock, openClie
     runEditorHandOff();
   };
 
-  // clicking the rail Share button: publish the plan, copy the ssh line
+  // clicking the header Share button: publish the plan, copy the ssh line
   const onShareRequest = (): void => {
     if (!isOwner) return controller.setStatus("only the plan owner can share");
     controller.share();
@@ -493,6 +499,7 @@ export function App({ home, sessionId, readOnly = false, onExit, clock, openClie
               editOrphanCount={editOrphanCount}
               onLineActivate={onLineActivate}
               onEditRequest={onEditRequest}
+              onShareRequest={onShareRequest}
               canEdit={isOwner}
             />
           )}
@@ -516,7 +523,6 @@ export function App({ home, sessionId, readOnly = false, onExit, clock, openClie
               onSelectCard: selectCardFromRail,
               onActivateCard: openCardEdit,
               onSubmitRequest,
-              onShareRequest: isOwner ? onShareRequest : undefined,
             }}
           />
         </box>

package/src/App.walk.test.tsx

@@ -184,8 +184,10 @@ describe("the guided walk", () => {
     // Assert
     await waitForText(second, "file 3 of 3 · 2 viewed");
     expect(second.captureCharFrame()).toContain("src/c.ts");
-    // two full App boots with daemon round-trips need more than the default budget
-  }, 15_000);
+    // two full App boots with daemon round-trips need more than the default
+    // budget, and the whole-suite publish lane has timed even 15s out; give the
+    // double-boot chain generous headroom so runner load cannot flake it.
+  }, 30_000);
 
   test("the agent-note block renders only for files carrying a note", async () => {
     // Arrange

package/src/components/PlanSheet.stories.tsx

@@ -6,7 +6,7 @@ import { fixtureDisplay, fixtureMarks, fixturePlanSession } from "./story-fixtur
 
 export const meta: StoryMeta = { title: "PlanSheet" };
 
-const callbacks = { onLineActivate: () => {}, onEditRequest: () => {}, canEdit: true };
+const callbacks = { onLineActivate: () => {}, onEditRequest: () => {}, onShareRequest: () => {}, canEdit: true };
 
 export const AnnotatedPlan: Story = {
   render: () => (

package/src/components/PlanSheet.tsx

@@ -64,7 +64,8 @@ export interface PlanSheetProps {
   editOrphanCount: number;
   onLineActivate: (displayIndex: number) => void;
   onEditRequest: () => void;
-  /** Owner-only: show the Edit affordance. A share viewer never sees it. */
+  onShareRequest: () => void;
+  /** Owner-only: show the Edit and Share affordances. A share viewer never sees either. */
   canEdit: boolean;
   theme?: Theme;
 }
@@ -99,6 +100,7 @@ export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function Pl
     editOrphanCount,
     onLineActivate,
     onEditRequest,
+    onShareRequest,
     canEdit,
     theme,
   }: PlanSheetProps,
@@ -218,7 +220,13 @@ export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function Pl
 
   return (
     <box style={{ flexGrow: 1, flexDirection: "column" }}>
-      <SheetHeader session={session} onEditRequest={onEditRequest} canEdit={canEdit} theme={theme} />
+      <SheetHeader
+        session={session}
+        onEditRequest={onEditRequest}
+        onShareRequest={onShareRequest}
+        canEdit={canEdit}
+        theme={theme}
+      />
       {editOrphanCount > 0 ? (
         <box style={{ height: 1, backgroundColor: tokens.markCommentBg, paddingLeft: 2 }}>
           <text fg={tokens.red}>
@@ -233,15 +241,17 @@ export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function Pl
   );
 });
 
-/** Sheet chrome: submitted-by + revision delta left, the Edit word-button right. */
+/** Sheet chrome: submitted-by + revision delta left, the Edit and Share word-buttons right. */
 function SheetHeader({
   session,
   onEditRequest,
+  onShareRequest,
   canEdit,
   theme,
 }: {
   session: ReviewSession;
   onEditRequest: () => void;
+  onShareRequest: () => void;
   canEdit: boolean;
   theme?: Theme;
 }): React.ReactNode {
@@ -260,11 +270,14 @@ function SheetHeader({
         ) : null}
       </text>
       <box style={{ flexGrow: 1 }} />
-      {canEdit ? (
+      {canEdit && session.status !== "resolved" ? (
         <Toolbar>
           <Button onPress={onEditRequest} theme={theme}>
             {" Edit "}
           </Button>
+          <Button onPress={onShareRequest} theme={theme}>
+            {" Share "}
+          </Button>
         </Toolbar>
       ) : null}
     </box>

package/src/components/ReviewRail.tsx

@@ -40,8 +40,6 @@ export interface ReviewRailProps {
   onSelectCard: (id: string) => void;
   onActivateCard: (id: string) => void;
   onSubmitRequest: () => void;
-  /** Publish the plan as a share; omitted for non-owners (hides the button). */
-  onShareRequest?: () => void;
   /** Rail column width; the app derives it from the persisted review layout. */
   width?: number;
   /**
@@ -70,7 +68,6 @@ export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function
     onSelectCard,
     onActivateCard,
     onSubmitRequest,
-    onShareRequest,
     width = 34,
     onCollapse,
     theme,
@@ -152,11 +149,6 @@ export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function
               {`Submit review (${pendingCount}) ⏎`}
             </Button>
           )}
-          {onShareRequest && session.status !== "resolved" ? (
-            <Button variant="plain" onPress={onShareRequest} theme={theme}>
-              {"Share plan ⇧S"}
-            </Button>
-          ) : null}
         </>
       )}
       {/* the collapse chevron: muted, left-bound, one column from the divider.

package/src/components/__snapshots__/stories.test.tsx.snap

@@ -489,7 +489,7 @@ exports[`stories catalog InboxList/TwoPending renders, snapshots, and carries it
 `;
 
 exports[`stories catalog PlanSheet/AnnotatedPlan renders, snapshots, and carries its colors: PlanSheet/AnnotatedPlan 1`] = `
-"  submitted by agent/worker-3 · revision 1                                          Edit  
+"  submitted by agent/worker-3 · revision 1                                   Edit  Share  
                                                                                           
     Migration Plan                                                                        
                                                                                           
@@ -521,7 +521,7 @@ exports[`stories catalog PlanSheet/AnnotatedPlan renders, snapshots, and carries
 `;
 
 exports[`stories catalog PlanSheet/InlineCompose renders, snapshots, and carries its colors: PlanSheet/InlineCompose 1`] = `
-"  submitted by agent/worker-3 · revision 1                                          Edit  
+"  submitted by agent/worker-3 · revision 1                                   Edit  Share  
                                                                                           
     Migration Plan                                                                        
                                                                                           
@@ -555,7 +555,7 @@ exports[`stories catalog PlanSheet/InlineCompose renders, snapshots, and carries
 `;
 
 exports[`stories catalog PlanSheet/OrphanBanner renders, snapshots, and carries its colors: PlanSheet/OrphanBanner 1`] = `
-"  submitted by agent/worker-3 · revision 1                                          Edit  
+"  submitted by agent/worker-3 · revision 1                                   Edit  Share  
   1 annotation no longer match - the passage was removed.                                 
                                                                                           
   ▎ Migration Plan                                                                        
@@ -587,7 +587,7 @@ exports[`stories catalog PlanSheet/OrphanBanner renders, snapshots, and carries
 `;
 
 exports[`stories catalog PlanSheet/SpanSelection renders, snapshots, and carries its colors: PlanSheet/SpanSelection 1`] = `
-"  submitted by agent/worker-3 · revision 1                                          Edit  
+"  submitted by agent/worker-3 · revision 1                                   Edit  Share  
                                                                                           
     Migration Plan                                                                        
                                                                                           

package/src/index.ts

@@ -1,4 +1,4 @@
 export { runClient, type RunClientOptions } from "./run";
 export { serveClient, type ServeHandle, type ServeOptions } from "./serve";
 export { App, type AppProps } from "./App";
-export { publishShare, type ShareResult, type ShareTarget } from "./share";
+export { collaboratorAnnotations, publishShare, pullShare, pushShare, shareIdFromLine, type ShareResult, type ShareTarget } from "./share";

package/src/session-controller.share.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, mock, test } from "bun:test";
+import { ManualClock } from "@opentui/core/testing";
+import { SCHEMA_VERSION, type Annotation, type ReviewSession } from "@cueloop/schema";
+import type { SessionClient } from "@cueloop/daemon/client";
+
+// Stub the ssh transport so no subprocess spawns; the controller under test
+// imports these from "./share".
+const publishShare = mock(async () => ({ line: "ssh p_abc123xy@cueloop.dev", copied: true }));
+let remote: ReviewSession;
+const pullShare = mock(async () => remote);
+const pushShare = mock(async (_shareId: string, _annotations: Array<Omit<Annotation, "createdAt">>) => {});
+mock.module("./share", () => ({
+  publishShare,
+  pullShare,
+  pushShare,
+  shareIdFromLine: (line: string) => line.match(/^ssh (\S+)@/)?.[1],
+  collaboratorAnnotations: (session: ReviewSession) => session.annotations.filter((annotation) => annotation.author),
+}));
+
+const { createReviewController, SHARE_POLL_MS } = await import("./session-controller");
+
+function sessionFixture(overrides: Partial<ReviewSession> = {}): ReviewSession {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_1",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# Plan\n", meta: {} },
+    revisions: [{ revision: 1, content: "# Plan\n", submittedAt: "2026-01-01T00:00:00.000Z" }],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+function annotation(id: string, author: string): Annotation {
+  return { id, kind: "comment", anchor: { quote: "Plan", prefix: "", suffix: "" }, body: "note", author, createdAt: "2026-01-01T00:00:00.000Z" };
+}
+
+function fakeClient(session: ReviewSession): SessionClient {
+  return {
+    onEvent: () => () => {},
+    subscribe: async () => {},
+    sessionGet: async () => session,
+    sessionList: async () => [session],
+    sessionAnnotate: mock(async () => session),
+    sessionSetShareId: mock(async (_id: string, shareId: string) => ((session.shareId = shareId), session)),
+    sessionMergeAnnotations: mock(async (_id: string, incoming: Annotation[]) => {
+      const known = new Set(session.annotations.map((existing) => existing.id));
+      for (const note of incoming) if (!known.has(note.id)) session.annotations.push(note);
+      return session;
+    }),
+    close: () => {},
+  } as unknown as SessionClient;
+}
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+async function connectedController(
+  session: ReviewSession,
+  clock?: ManualClock,
+): Promise<{ controller: ReturnType<typeof createReviewController>; client: SessionClient }> {
+  const client = fakeClient(session);
+  const controller = createReviewController({ sessionId: session.id, openClient: async () => client, clock });
+  controller.connect();
+  await tick();
+  return { controller, client };
+}
+
+describe("share", () => {
+  test("stamps the returned share id back on the session", async () => {
+    // Arrange
+    const { controller, client } = await connectedController(sessionFixture());
+
+    // Act
+    controller.share();
+    await tick();
+
+    // Assert
+    expect(client.sessionSetShareId).toHaveBeenCalledWith("ses_1", "p_abc123xy");
+  });
+});
+
+describe("pullShared", () => {
+  test("unions collaborator notes in when the plan was shared", async () => {
+    // Arrange
+    remote = sessionFixture({ annotations: [annotation("a1", "SHA256:mate")] });
+    const { controller, client } = await connectedController(sessionFixture({ shareId: "p_abc123xy" }));
+
+    // Act
+    controller.pullShared();
+    await tick();
+
+    // Assert
+    expect(pullShare).toHaveBeenCalledWith("p_abc123xy");
+    expect(client.sessionMergeAnnotations).toHaveBeenCalledWith("ses_1", remote.annotations);
+  });
+
+  test("does nothing for a plan that was never shared", async () => {
+    // Arrange
+    pullShare.mockClear();
+    const { controller, client } = await connectedController(sessionFixture());
+
+    // Act
+    controller.pullShared();
+    await tick();
+
+    // Assert
+    expect(pullShare).not.toHaveBeenCalled();
+    expect(client.sessionMergeAnnotations).not.toHaveBeenCalled();
+  });
+});
+
+describe("mirror on annotate", () => {
+  test("pushes an edited note up when the plan is shared", async () => {
+    // Arrange
+    pushShare.mockClear();
+    const { controller } = await connectedController(sessionFixture({ shareId: "p_abc123xy", annotations: [annotation("a1", "SHA256:me")] }));
+
+    // Act
+    controller.updateAnnotation("a1", "revised body");
+    await tick();
+
+    // Assert
+    expect(pushShare).toHaveBeenCalledTimes(1);
+    expect(pushShare.mock.calls[0]?.[0]).toBe("p_abc123xy");
+    expect(pushShare.mock.calls[0]?.[1]).toEqual([{ id: "a1", kind: "comment", anchor: { quote: "Plan", prefix: "", suffix: "" }, body: "revised body" }]);
+  });
+
+  test("does not push when the plan was never shared", async () => {
+    // Arrange
+    pushShare.mockClear();
+    const { controller } = await connectedController(sessionFixture({ annotations: [annotation("a1", "SHA256:me")] }));
+
+    // Act
+    controller.updateAnnotation("a1", "revised body");
+    await tick();
+
+    // Assert
+    expect(pushShare).not.toHaveBeenCalled();
+  });
+
+  test("does not push when the local write is rejected", async () => {
+    // Arrange - the daemon write fails (e.g. a resolved session)
+    pushShare.mockClear();
+    const { controller, client } = await connectedController(sessionFixture({ shareId: "p_abc123xy", annotations: [annotation("a1", "SHA256:me")] }));
+    (client.sessionAnnotate as ReturnType<typeof mock>).mockImplementationOnce(async () => {
+      throw new Error("session is resolved");
+    });
+
+    // Act
+    controller.updateAnnotation("a1", "revised body");
+    await tick();
+
+    // Assert - a failed local write must never leak to the share
+    expect(pushShare).not.toHaveBeenCalled();
+  });
+});
+
+describe("startSharePoll", () => {
+  test("pulls now and again each interval until stopped", async () => {
+    // Arrange
+    pullShare.mockClear();
+    remote = sessionFixture({ annotations: [] });
+    const clock = new ManualClock();
+    const { controller } = await connectedController(sessionFixture({ shareId: "p_abc123xy" }), clock);
+
+    // Act - immediate pull
+    const stop = controller.startSharePoll();
+    await tick();
+
+    // Assert
+    expect(pullShare).toHaveBeenCalledTimes(1);
+
+    // Act - one interval later, it pulls again
+    clock.advance(SHARE_POLL_MS);
+    await tick();
+
+    // Assert
+    expect(pullShare).toHaveBeenCalledTimes(2);
+
+    // Act - stop, then advance: no further pulls
+    stop();
+    clock.advance(SHARE_POLL_MS * 3);
+    await tick();
+
+    // Assert
+    expect(pullShare).toHaveBeenCalledTimes(2);
+  });
+
+  test("a stop during an in-flight pull leaves no zombie timer", async () => {
+    // Arrange - the first pull hangs until released
+    pullShare.mockClear();
+    remote = sessionFixture({ annotations: [] });
+    let release: () => void = () => {};
+    pullShare.mockImplementationOnce(() => new Promise<ReviewSession>((resolve) => (release = () => resolve(remote))));
+    const clock = new ManualClock();
+    const { controller } = await connectedController(sessionFixture({ shareId: "p_abc123xy" }), clock);
+
+    // Act - start (pull is in flight), leave, then let the pull settle
+    const stop = controller.startSharePoll();
+    await tick();
+    expect(pullShare).toHaveBeenCalledTimes(1);
+    stop();
+    release();
+    await tick();
+    clock.advance(SHARE_POLL_MS * 3);
+    await tick();
+
+    // Assert - the settled pull's finally must not re-arm the timer
+    expect(pullShare).toHaveBeenCalledTimes(1);
+  });
+
+  test("a restart during an in-flight pull does not double the poll", async () => {
+    // Arrange - run A's first pull hangs; later pulls resolve immediately
+    pullShare.mockClear();
+    remote = sessionFixture({ annotations: [] });
+    let release: () => void = () => {};
+    pullShare.mockImplementationOnce(() => new Promise<ReviewSession>((resolve) => (release = () => resolve(remote))));
+    const clock = new ManualClock();
+    const { controller } = await connectedController(sessionFixture({ shareId: "p_abc123xy" }), clock);
+
+    // Act - run A starts (pull hangs), then run B restarts while A is in flight
+    controller.startSharePoll();
+    await tick();
+    expect(pullShare).toHaveBeenCalledTimes(1);
+    const stopB = controller.startSharePoll();
+    await tick();
+    expect(pullShare).toHaveBeenCalledTimes(2);
+
+    // A's stale pull settles - it must not re-arm; then one interval fires only run B
+    release();
+    await tick();
+    clock.advance(SHARE_POLL_MS);
+    await tick();
+
+    // Assert - exactly one more pull (run B), not two
+    expect(pullShare).toHaveBeenCalledTimes(3);
+    stopB();
+  });
+});

package/src/session-controller.ts

@@ -19,11 +19,12 @@ import {
   restoreBlock,
   restoreLine,
   returnPaneFor,
+  type Annotation,
   type ReviewSession,
   type VerdictKind,
 } from "@cueloop/schema";
 import { loadBundledExporters, type BundledExporter } from "./integrations";
-import { publishShare } from "./share";
+import { collaboratorAnnotations, publishShare, pullShare, pushShare, shareIdFromLine } from "./share";
 import { buildDisplay, nextWorkBlock, type DisplayBlock } from "./view-plan";
 import { diffRowAnchor, diffRows, type DiffRow } from "./view-diff";
 import { firstUnviewedIndex, walkFiles, type WalkFile } from "./walk";
@@ -46,6 +47,9 @@ export type Completion =
 /** Seconds the completion overlay counts down before it hands back. */
 export const DEFAULT_AUTO_CLOSE = 5;
 
+/** How often an open shared plan re-pulls collaborator notes (ADR 0005 stage 2). */
+export const SHARE_POLL_MS = 4000;
+
 export interface ControllerSnapshot {
   session: ReviewSession | null;
   inbox: ReviewSession[] | null;
@@ -124,6 +128,10 @@ export interface ReviewController {
   submit(verdict: VerdictKind, summary: string): void;
   /** Publish the current session as a share; the ssh line lands on the clipboard. */
   share(): void;
+  /** Pull a shared plan's collaborator notes back and union them in (planner only). */
+  pullShared(): Promise<void>;
+  /** Poll the share for collaborator notes while it is open; returns a stop handle. */
+  startSharePoll(): () => void;
   /** Close the review and, inside herdr, bounce focus back to the agent. */
   finishReview(): void;
   dismissCompletion(): void;
@@ -160,6 +168,8 @@ class Controller implements ReviewController {
   private exporters: BundledExporter[] = [];
   private readonly clock: Clock;
   private countdown: TimerHandle | undefined;
+  private sharePoll: TimerHandle | undefined;
+  private shareRun: object | null = null;
   /** Projections keyed by session identity so renders reuse one computation. */
   private derivedFor: ReviewSession | null = null;
   private derived: { display: DisplayBlock[]; rows: DiffRow[]; files: WalkFile[] } = {
@@ -213,6 +223,7 @@ class Controller implements ReviewController {
   close(): void {
     this.closed = true;
     this.clearCountdown();
+    this.stopSharePoll();
     this.client?.close();
   }
 
@@ -366,17 +377,12 @@ class Controller implements ReviewController {
       const workBlockIndex = display.slice(0, displayIndex + 1).filter((entry) => entry.work).length - 1;
       anchor = makeAnchor(workBlocks, workBlockIndex, start, end);
     }
-    const annotationId = newAnnotationId();
-    this.apply(
-      this.client!.sessionAnnotate(session.id, {
-        id: annotationId,
-        kind,
-        anchor,
-        body,
-      }),
-    );
+    const wire = { id: newAnnotationId(), kind, anchor, body };
+    const persisted = this.client!.sessionAnnotate(session.id, wire);
+    this.apply(persisted);
+    this.mirrorAnnotation(persisted, wire);
     this.setStatus(kind === "suggestion" ? "suggestion added - the agent applies it" : "comment added");
-    return annotationId;
+    return wire.id;
   }
 
   updateAnnotation(id: string, body: string): void {
@@ -385,17 +391,20 @@ class Controller implements ReviewController {
     const existing = session.annotations.find((annotation) => annotation.id === id);
     if (!existing) return;
     // the daemon's annotate verb upserts by id: same id + anchor, new body
-    this.apply(
-      this.client!.sessionAnnotate(session.id, {
-        id: existing.id,
-        kind: existing.kind,
-        anchor: existing.anchor,
-        body,
-      }),
-    );
+    const wire = { id: existing.id, kind: existing.kind, anchor: existing.anchor, body };
+    const persisted = this.client!.sessionAnnotate(session.id, wire);
+    this.apply(persisted);
+    this.mirrorAnnotation(persisted, wire);
     this.setStatus("annotation updated");
   }
 
+  // push only after the local write lands, so a rejected write never leaks to the share
+  private mirrorAnnotation(persisted: Promise<ReviewSession>, annotation: Omit<Annotation, "createdAt">): void {
+    const shareId = this.snapshot.session?.shareId;
+    if (!shareId) return;
+    void persisted.then(() => pushShare(shareId, [annotation])).catch(() => {});
+  }
+
   removeAnnotation(id: string): void {
     const session = this.snapshot.session;
     if (!session) return;
@@ -485,10 +494,58 @@ class Controller implements ReviewController {
     if (!session) return;
     this.setStatus("sharing…");
     publishShare(session)
-      .then(({ line, copied }) => this.setStatus(copied ? `✓ share link copied - ${line}` : line))
+      .then(async ({ line, copied }) => {
+        // Stamp the id back so a later pull knows which share to collect from.
+        const shareId = shareIdFromLine(line);
+        if (shareId && this.client) await this.client.sessionSetShareId(session.id, shareId);
+        this.setStatus(copied ? `✓ share link copied - ${line}` : line);
+      })
       .catch((error: unknown) => this.setStatus(`share failed: ${error instanceof Error ? error.message : String(error)}`));
   }
 
+  /**
+   * Pull collaborator notes for a shared plan and union them in, awaiting the
+   * merge so a poll never overlaps rounds. The daemon's merge emits
+   * session.updated, so the re-render happens through the normal event path.
+   * Best-effort: a failed refresh is silent and the next tick retries.
+   */
+  pullShared(): Promise<void> {
+    const session = this.snapshot.session;
+    if (!session?.shareId || !this.client) return Promise.resolve();
+    const client = this.client;
+    return pullShare(session.shareId)
+      .then((remote) => client.sessionMergeAnnotations(session.id, collaboratorAnnotations(remote)))
+      .then(() => {})
+      .catch(() => {});
+  }
+
+  /**
+   * Poll the share for collaborator notes while it is open: pull now, then again
+   * every few seconds, each round waiting for the last so slow pulls never stack.
+   * Returns a stop handle the caller runs on leave.
+   */
+  startSharePoll(): () => void {
+    this.stopSharePoll();
+    // per-run token so a stale run's in-flight pull never re-arms the poll
+    const run = {};
+    this.shareRun = run;
+    const tick = (): void => {
+      void this.pullShared().finally(() => {
+        if (this.shareRun === run && !this.closed) this.sharePoll = this.clock.setTimeout(tick, SHARE_POLL_MS);
+      });
+    };
+    tick();
+    return () => {
+      if (this.shareRun === run) this.stopSharePoll();
+    };
+  }
+
+  private stopSharePoll(): void {
+    this.shareRun = null;
+    if (this.sharePoll !== undefined) this.clock.clearTimeout(this.sharePoll);
+    this.sharePoll = undefined;
+  }
+
   // ── completion hand-back ────────────────────
   private startCounting(remaining: number): void {
     if (remaining <= 0) return this.finishReview();

package/src/share.ts

@@ -7,7 +7,7 @@
  */
 
 import { DEFAULT_SHARE_HOST, DEFAULT_SHARE_PORT, SHARE_UPLOAD_USER, packSessionBlob } from "@cueloop/daemon/share-blob";
-import type { ReviewSession } from "@cueloop/schema";
+import type { Annotation, ReviewSession } from "@cueloop/schema";
 import { copyToClipboard } from "./clipboard";
 
 export interface ShareTarget {
@@ -22,26 +22,59 @@ export interface ShareResult {
   copied: boolean;
 }
 
+/** The `p_…` share id inside a `ssh p_…@host` line, or undefined. */
+export function shareIdFromLine(line: string): string | undefined {
+  return line.match(/^ssh (\S+)@/)?.[1];
+}
+
 /** Upload the session to the gateway and copy the resulting ssh line. */
 export async function publishShare(session: ReviewSession, target: ShareTarget = {}): Promise<ShareResult> {
-  const line = await uploadOverSsh(packSessionBlob(session), target.host ?? DEFAULT_SHARE_HOST, target.port ?? DEFAULT_SHARE_PORT);
+  const { stdout, stderr, code } = await runShareSsh("cueloop-share", packSessionBlob(session), target);
+  if (code !== 0) throw new Error(`gateway upload failed: ${stderr.trim() || `ssh exited ${code}`}`);
+  const line = stdout.trim();
+  if (!line.startsWith("ssh ")) throw new Error(`unexpected gateway reply: ${line || "(empty)"}`);
   const copied = await copyToClipboard(line);
   return { line, copied };
 }
 
-/** Stream the blob to `share@host:port` over the system `ssh` client. */
-async function uploadOverSsh(blob: Buffer, host: string, port: number): Promise<string> {
+/**
+ * Pull a share's current session back from the gateway. The gateway lets only
+ * the fingerprint that uploaded it through, so collaborator notes reach the
+ * planner without exposing the master key.
+ */
+export async function pullShare(shareId: string, target: ShareTarget = {}): Promise<ReviewSession> {
+  const { stdout, stderr, code } = await runShareSsh("cueloop-pull", Buffer.from(shareId), target);
+  if (code !== 0) throw new Error(`gateway pull failed: ${stderr.trim() || `ssh exited ${code}`}`);
+  return JSON.parse(stdout) as ReviewSession;
+}
+
+/** A share's collaborator notes: the ones a viewer authored (author stamped). */
+export function collaboratorAnnotations(session: ReviewSession): Annotation[] {
+  return session.annotations.filter((annotation) => annotation.author);
+}
+
+/**
+ * Mirror the planner's own annotations up into the share, so collaborators see
+ * them on their next refresh. Owner-gated at the gateway; the notes stay
+ * unauthored (the planner's), unioned by id.
+ */
+export async function pushShare(shareId: string, annotations: Array<Omit<Annotation, "createdAt">>, target: ShareTarget = {}): Promise<void> {
+  const { stderr, code } = await runShareSsh("cueloop-push", Buffer.from(JSON.stringify({ shareId, annotations })), target);
+  if (code !== 0) throw new Error(`gateway push failed: ${stderr.trim() || `ssh exited ${code}`}`);
+}
+
+/** Run one `share@host:port` ssh command with `stdin`; hand back its streams and exit code. */
+async function runShareSsh(command: string, stdin: Buffer, target: ShareTarget): Promise<{ stdout: string; stderr: string; code: number }> {
+  const host = target.host ?? DEFAULT_SHARE_HOST;
+  const port = target.port ?? DEFAULT_SHARE_PORT;
   const proc = Bun.spawn(
-    ["ssh", "-p", String(port), "-o", "StrictHostKeyChecking=accept-new", `${SHARE_UPLOAD_USER}@${host}`, "cueloop-share"],
-    { stdin: blob, stdout: "pipe", stderr: "pipe" },
+    ["ssh", "-p", String(port), "-o", "StrictHostKeyChecking=accept-new", `${SHARE_UPLOAD_USER}@${host}`, command],
+    { stdin, stdout: "pipe", stderr: "pipe" },
   );
   const [stdout, stderr, code] = await Promise.all([
     new Response(proc.stdout).text(),
     new Response(proc.stderr).text(),
     proc.exited,
   ]);
-  if (code !== 0) throw new Error(`gateway upload failed: ${stderr.trim() || `ssh exited ${code}`}`);
-  const line = stdout.trim();
-  if (!line.startsWith("ssh ")) throw new Error(`unexpected gateway reply: ${line || "(empty)"}`);
-  return line;
+  return { stdout, stderr, code };
 }