cueloop 0.1.0-alpha.63 → 0.1.0-alpha.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.63",
+  "version": "0.1.0-alpha.65",
   "description": "Terminal review surface for coding agents: annotate plans and diffs, return a verdict, send structured feedback back",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -30,10 +30,11 @@
     "build:binary": "bun build --compile --external cpu-features ./src/main.ts --outfile dist/cueloop"
   },
   "dependencies": {
-    "@cueloop/adapters": "0.1.0-alpha.63",
-    "@cueloop/client": "0.1.0-alpha.63",
-    "@cueloop/daemon": "0.1.0-alpha.63",
-    "@cueloop/schema": "0.1.0-alpha.63"
+    "@cueloop/adapters": "0.1.0-alpha.65",
+    "@cueloop/client": "0.1.0-alpha.65",
+    "@cueloop/daemon": "0.1.0-alpha.65",
+    "@cueloop/schema": "0.1.0-alpha.65",
+    "valibot": "^1.4.2"
   },
   "engines": {
     "bun": ">=1.3.0"

package/src/actions-command.ts

@@ -12,9 +12,9 @@ import { parseArgs, stringFlag } from "./args";
 
 export async function actionsCommand(argv: string[]): Promise<number> {
   const { positional, flags } = parseArgs(argv);
-  const verb = positional[0] ?? "list";
+  const primitive = positional[0] ?? "list";
 
-  if (verb !== "list") {
+  if (primitive !== "list") {
     console.error("usage: cueloop actions list [--session <id>]");
 
     return 2;

package/src/args.ts

@@ -1,5 +1,7 @@
 /** Tiny flag parser: --key value, --key=value, boolean --flag, positionals. */
 
+import * as v from "valibot";
+
 export interface ParsedArgs {
   positional: string[];
   flags: Record<string, string | boolean>;
@@ -40,7 +42,7 @@ export function stringFlag(
   flags: Record<string, string | boolean>,
   key: string,
 ): string | undefined {
-  const value = flags[key];
+  const result = v.safeParse(v.string(), flags[key]);
 
-  return typeof value === "string" ? value : undefined;
+  return result.success ? result.output : undefined;
 }

package/src/main.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * cueloop entry points: `cueloop` opens the TUI on the inbox, the verb-first
+ * cueloop entry points: `cueloop` opens the TUI on the inbox, the primitive-first
  * openers `cueloop plan|reply|diff|review` open the latest pending review of
  * that type (or address one by id/title), `cueloop diff`/`cueloop review <pr>` also
  * keep their create paths, `cueloop session *` mirrors the daemon API for
@@ -93,12 +93,16 @@ async function shareEntry(rest: string[]): Promise<number> {
 
   if (positional[0] === "pull") return sharePullCommand({ ...target, sessionId: positional[1] });
 
-  return shareCommand({ ...target, sessionId: positional[0] });
+  return shareCommand({ ...target, sessionId: positional[0], fork: flags.fork === true });
 }
 
 type CommandHandler = (rest: string[]) => number | Promise<number>;
 
-const commandHandlers: Record<string, CommandHandler> = {
+interface CommandHandlers {
+  [command: string]: CommandHandler;
+}
+
+const commandHandlers: CommandHandlers = {
   session: (rest) => sessionCommand(rest),
   daemon: (rest) => daemonCommand(rest),
   plan: (rest) => planCommand(rest),
@@ -139,7 +143,7 @@ async function main(): Promise<number> {
 }
 
 /**
- * The id-or-title selector for a verb-first opener: the bare positional, or a
+ * The id-or-title selector for a primitive-first opener: the bare positional, or a
  * value handed to `--open`/`--latest`. A bare `--latest`/`--open` flag carries
  * no value, so the selector stays undefined and the opener defaults to the
  * latest pending review.
@@ -151,7 +155,7 @@ function openSelector(parsed: ParsedArgs): string | undefined {
 }
 
 /**
- * Resolve one review of the verb's scope and open it in the TUI, or print the
+ * Resolve one review of the primitive's scope and open it in the TUI, or print the
  * miss and fail. `emptyMessage` overrides the default no-pending line for the
  * one caller that needs a scope-specific hint (a clean working tree).
  */
@@ -336,7 +340,7 @@ function printHelp(): void {
       "  cueloop <plan|diff|review> --latest  open the latest pending review of that type",
       "",
       "scripting:",
-      "  cueloop session <verb> [flags]   script the daemon (create|get|list|wait|annotate|resolve|submit-revision)",
+      "  cueloop session <primitive> [flags]   script the daemon (create|get|list|wait|annotate|remove|cut|restore|curate|set-viewed|navigate|branch|switch|label|fork|name-self|events|resolve|submit-revision)",
       "  cueloop actions list             list the quick-action vocabulary (for annotate --action)",
       "  cueloop refine                   mine past reviews into a markdown report + writeback proposals",
       "  cueloop wake <id> [--harness codex --thread <id>]  resume the agent with the verdict (spawn detached)",

package/src/open-target.test.ts

@@ -1,4 +1,4 @@
-/** Verb-first open resolution over a plain session list: latest-pending default, by-id, and fuzzy-by-title (exact wins, unique substring wins, else ambiguous). Pure over the array - no daemon, no TUI. */
+/** Primitive-first open resolution over a plain session list: latest-pending default, by-id, and fuzzy-by-title (exact wins, unique substring wins, else ambiguous). Pure over the array - no daemon, no TUI. */
 
 import { describe, expect, test } from "bun:test";
 import type { ArtifactType, ReviewSession } from "@cueloop/schema";
@@ -43,7 +43,7 @@ function session(overrides: {
 
 const isPlan = isPlanReview;
 
-describe("verb scope predicates are disjoint", () => {
+describe("primitive scope predicates are disjoint", () => {
   test("isPlanReview matches only plan artifacts", () => {
     expect(isPlanReview(session({ id: "ses_p", type: "plan" }))).toBe(true);
     expect(isPlanReview(session({ id: "ses_d", type: "diff" }))).toBe(false);

package/src/open-target.ts

@@ -1,5 +1,5 @@
 /**
- * Verb-first review-open resolution: turn a verb (plan/diff/review) plus an
+ * Primitive-first review-open resolution: turn a primitive (plan/diff/review) plus an
  * optional id-or-title selector into a single session to open, or a clear
  * miss. Pure over a session list so it unit-tests without a daemon or a TUI -
  * main.ts fetches the sessions and prints the miss messages.
@@ -12,15 +12,15 @@
  *   - otherwise the selector matches session titles, case-insensitive: an
  *     exact title wins, else a unique substring match wins, else the substring
  *     candidates are reported as ambiguous.
- * Every lookup is scoped by the caller's `match` predicate, so a verb only
+ * Every lookup is scoped by the caller's `match` predicate, so a primitive only
  * ever resolves to its own artifact kind.
  */
 
 import type { ReviewSession } from "@cueloop/schema";
 
 /**
- * The verb scopes, kept disjoint on purpose so a single session never resolves
- * under two verbs. A PR review is a diff artifact that carries a `pr`
+ * The primitive scopes, kept disjoint on purpose so a single session never resolves
+ * under two primitives. A PR review is a diff artifact that carries a `pr`
  * reference (openReview maps a top-level `pr` into `meta.pr`), so the plain
  * diff scope must exclude those - otherwise `cueloop diff` and `cueloop
  * review` would both open the same pending PR review.
@@ -47,7 +47,7 @@ export function isSessionId(value: string): boolean {
 }
 
 export interface OpenTargetQuery {
-  /** Only sessions this predicate accepts are eligible - the verb's artifact scope. */
+  /** Only sessions this predicate accepts are eligible - the primitive's artifact scope. */
   match: (session: ReviewSession) => boolean;
   /** Positional id-or-title selector; absent means "latest pending". */
   selector?: string;
@@ -107,7 +107,7 @@ export function resolveOpenTarget(sessions: ReviewSession[], query: OpenTargetQu
 
 /**
  * The reviewer-facing line for a miss, in the "working tree is clean - nothing
- * to review" tone. `label` is the human word for the verb's scope ("plan",
+ * to review" tone. `label` is the human word for the primitive's scope ("plan",
  * "diff", "PR"). The "session" outcome has no message - the caller opens it.
  */
 export function openTargetMessage(

package/src/session-commands.ts

@@ -4,10 +4,17 @@
  * JSON on stdout; exit code 0 unless the daemon returned an error.
  */
 
-import { ARTIFACT_TYPES, isArtifactType, newAnnotationId, type VerdictKind } from "@cueloop/schema";
+import {
+  ARTIFACT_TYPES,
+  isArtifactType,
+  newAnnotationId,
+  type Anchor,
+  type Annotation,
+} from "@cueloop/schema";
+import * as v from "valibot";
 import { DaemonClient } from "@cueloop/daemon/client";
 import { openHerdrPaneForReview } from "@cueloop/daemon/herdr-pane";
-import { openReview, verdictResponse, type ReviewNote } from "@cueloop/daemon/review";
+import { openReview, verdictResponse } from "@cueloop/daemon/review";
 import { loadConfig, quickActionBody, resolveQuickAction } from "@cueloop/client/config";
 import { parseArgs, stringFlag } from "./args";
 
@@ -15,10 +22,14 @@ async function readStdin(): Promise<string> {
   return await new Response(Bun.stdin.stream()).text();
 }
 
-function out(value: unknown): void {
+function out(value: Parameters<typeof JSON.stringify>[0]): void {
   console.log(JSON.stringify(value, null, 2));
 }
 
+const ReviewNotesSchema = v.array(v.object({ path: v.string(), body: v.string() }));
+const SessionStatusSchema = v.picklist(["pending", "resolved"]);
+const VerdictKindSchema = v.picklist(["comment", "approve", "request_changes"]);
+
 type SessionFlags = Record<string, string | boolean>;
 type SessionContext = { client: DaemonClient; positional: string[]; flags: SessionFlags };
 type SessionVerbHandler = (context: SessionContext) => Promise<number>;
@@ -35,7 +46,7 @@ async function sessionCreate({ client, flags }: SessionContext): Promise<number>
   // per-file agent notes for diff sessions: a JSON array of { path, body }
   const notesFile = stringFlag(flags, "notes-file");
   const notes = notesFile
-    ? (JSON.parse(await Bun.file(notesFile).text()) as ReviewNote[])
+    ? v.parse(ReviewNotesSchema, JSON.parse(await Bun.file(notesFile).text()))
     : undefined;
   const review = await openReview(client, {
     type,
@@ -63,7 +74,8 @@ async function sessionGetCommand({ client, positional }: SessionContext): Promis
 }
 
 async function sessionListCommand({ client, flags }: SessionContext): Promise<number> {
-  const status = stringFlag(flags, "status") as "pending" | "resolved" | undefined;
+  const rawStatus = stringFlag(flags, "status");
+  const status = rawStatus ? v.parse(SessionStatusSchema, rawStatus) : undefined;
 
   out(await client.sessionList(status ? { status } : undefined));
 
@@ -87,44 +99,249 @@ async function sessionWaitCommand({ client, positional, flags }: SessionContext)
   return 0;
 }
 
+/**
+ * The anchor an annotate call means: a reply borrows its root comment's
+ * anchor, a prototype comment names an element by selector, and anything
+ * else quotes the passage.
+ */
+async function annotateAnchor(
+  flags: Record<string, string | boolean>,
+  client: DaemonClient,
+  id: string,
+): Promise<{ anchor: Anchor; replyTo?: string }> {
+  const replyTo = stringFlag(flags, "reply-to");
+
+  if (replyTo !== undefined) {
+    const session = await client.sessionGet(id);
+    const root = session.annotations.find((annotation) => annotation.id === replyTo);
+
+    if (!root) throw new Error(`no comment ${replyTo} to reply to`);
+
+    // a reply to a reply still hangs off the discussion's root comment
+    return { anchor: root.anchor, replyTo: root.replyTo ?? root.id };
+  }
+  const selector = stringFlag(flags, "selector");
+  const quote =
+    selector === undefined
+      ? required(stringFlag(flags, "quote"), "--quote")
+      : (stringFlag(flags, "quote") ?? "");
+  const anchor: Anchor = {
+    quote,
+    prefix: stringFlag(flags, "prefix") ?? "",
+    suffix: stringFlag(flags, "suffix") ?? "",
+  };
+
+  if (selector !== undefined) anchor.selector = selector;
+
+  return { anchor };
+}
+
 async function sessionAnnotateCommand({
   client,
   positional,
   flags,
 }: SessionContext): Promise<number> {
   const id = required(positional[1], "session id");
-  const quote = required(stringFlag(flags, "quote"), "--quote");
   const author = stringFlag(flags, "author");
   const body = await annotateBody(flags, client, id);
+  const { anchor, replyTo } = await annotateAnchor(flags, client, id);
+  const annotation: Omit<Annotation, "createdAt"> = {
+    id: stringFlag(flags, "annotation-id") ?? newAnnotationId(),
+    kind: stringFlag(flags, "kind") ?? "comment",
+    anchor,
+    body,
+    author,
+  };
+
+  if (replyTo !== undefined) annotation.replyTo = replyTo;
+  out(await client.sessionAnnotate(id, annotation, stringFlag(flags, "author-name")));
+
+  return 0;
+}
+
+/** Remove a comment; a non-owner connection removes only the comments of the author it is bound to. */
+async function sessionRemoveCommand({ client, positional }: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+  const annotationId = required(positional[2], "annotation id");
+
+  out(await client.sessionRemoveAnnotation(id, annotationId));
+
+  return 0;
+}
+
+/** A 0-based block or line index as the command line carries it. */
+const BlockIndexSchema = v.pipe(v.string(), v.transform(Number), v.integer(), v.minValue(0));
+
+/** The reject decisions of a diff review as `--rejections` carries them. */
+const RejectionsSchema = v.array(
+  v.object({
+    path: v.pipe(v.string(), v.minLength(1)),
+    hunkIndex: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    changeIndex: v.optional(v.pipe(v.number(), v.integer(), v.minValue(0))),
+  }),
+);
+
+/** Cut the given block of the working copy (a 0-based index into its blocks). */
+async function sessionCutCommand({ client, positional }: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+  const blockIndex = v.parse(BlockIndexSchema, required(positional[2], "block index"));
+
+  out(await client.sessionCutBlock(id, blockIndex));
+
+  return 0;
+}
+
+/** Re-insert a cut block of the submitted revision, before --line (default: the end). */
+async function sessionRestoreCommand({
+  client,
+  positional,
+  flags,
+}: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+  const baseBlockIndex = v.parse(BlockIndexSchema, required(positional[2], "block index"));
+  const line = stringFlag(flags, "line");
 
   out(
-    await client.sessionAnnotate(
+    await client.sessionRestoreBlock(
       id,
-      {
-        id: stringFlag(flags, "annotation-id") ?? newAnnotationId(),
-        kind: stringFlag(flags, "kind") ?? "comment",
-        anchor: {
-          quote,
-          prefix: stringFlag(flags, "prefix") ?? "",
-          suffix: stringFlag(flags, "suffix") ?? "",
-        },
-        body,
-        ...(author ? { author } : {}),
-      },
-      stringFlag(flags, "author-name"),
+      baseBlockIndex,
+      line === undefined ? undefined : v.parse(BlockIndexSchema, line),
     ),
   );
 
   return 0;
 }
 
+/** Replace a diff review's reject decisions with the JSON list given. */
+async function sessionCurateCommand({
+  client,
+  positional,
+  flags,
+}: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+  const rejections = v.parse(
+    RejectionsSchema,
+    JSON.parse(required(stringFlag(flags, "rejections"), "--rejections")),
+  );
+
+  out(await client.sessionCurate(id, rejections));
+
+  return 0;
+}
+
+/** Move a branch's tip back to an entry on its path; --summary records what was left behind, --branch stands on that branch first. */
+async function sessionNavigateCommand({
+  client,
+  positional,
+  flags,
+}: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+  const entryId = required(positional[2], "entry id");
+
+  out(
+    await client.sessionNavigate(
+      id,
+      entryId,
+      stringFlag(flags, "summary"),
+      stringFlag(flags, "branch"),
+    ),
+  );
+
+  return 0;
+}
+
+/** Start a branch at the current tip and switch to it. */
+async function sessionBranchCommand({ client, positional }: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+
+  out(await client.sessionBranch(id, required(positional[2], "branch name")));
+
+  return 0;
+}
+
+/** Show another branch's path. */
+async function sessionSwitchCommand({ client, positional }: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+
+  out(await client.sessionSwitch(id, required(positional[2], "branch name")));
+
+  return 0;
+}
+
+/** Name the current tip as a checkpoint. */
+async function sessionLabelCommand({ client, positional }: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+
+  out(await client.sessionLabel(id, required(positional[2], "label")));
+
+  return 0;
+}
+
+/** Copy the current path into a new session and print the fork. */
+async function sessionForkCommand({ client, positional }: SessionContext): Promise<number> {
+  out(await client.sessionFork(required(positional[1], "session id")));
+
+  return 0;
+}
+
+/** Mark files of a diff review as viewed - the guided walk's state, from a script. */
+async function sessionSetViewedCommand({ client, positional }: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+
+  out(await client.sessionSetViewed(id, positional.slice(2)));
+
+  return 0;
+}
+
+/** Register the display name of a participant: how a collaborator or an agent names itself. */
+async function sessionNameSelfCommand({
+  client,
+  positional,
+  flags,
+}: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+  const name = required(positional[2], "name");
+  const author = required(stringFlag(flags, "author"), "--author");
+
+  out(await client.sessionSetParticipantName(id, author, name));
+
+  return 0;
+}
+
+/**
+ * Follow a session live: one JSON line per event, with the entry the change
+ * appended, until the process ends. `--once` prints the first event and exits.
+ * The subscription is in place before the session is read, so nothing that
+ * lands after the read can slip between the two.
+ */
+async function sessionEventsCommand({
+  client,
+  positional,
+  flags,
+}: SessionContext): Promise<number> {
+  const id = required(positional[1], "session id");
+  const once = flags.once === true;
+  const stream = new Promise<number>((resolve) => {
+    client.onEvent((event) => {
+      if (event.sessionId !== id) return;
+      out(event);
+      if (once) resolve(0);
+    });
+  });
+
+  await client.subscribe();
+  await client.sessionGet(id);
+
+  return stream;
+}
+
 async function sessionResolveCommand({
   client,
   positional,
   flags,
 }: SessionContext): Promise<number> {
   const id = required(positional[1], "session id");
-  const kind = required(stringFlag(flags, "verdict"), "--verdict") as VerdictKind;
+  const kind = v.parse(VerdictKindSchema, required(stringFlag(flags, "verdict"), "--verdict"));
 
   out(await client.sessionResolve(id, kind, stringFlag(flags, "summary") ?? ""));
 
@@ -150,30 +367,51 @@ async function sessionSubmitRevisionCommand({
   return 0;
 }
 
-const sessionVerbHandlers: Record<string, SessionVerbHandler> = {
+interface SessionVerbHandlers {
+  [primitive: string]: SessionVerbHandler;
+}
+
+const sessionVerbHandlers: SessionVerbHandlers = {
   create: sessionCreate,
   get: sessionGetCommand,
   list: sessionListCommand,
   wait: sessionWaitCommand,
   annotate: sessionAnnotateCommand,
+  remove: sessionRemoveCommand,
+  cut: sessionCutCommand,
+  restore: sessionRestoreCommand,
+  curate: sessionCurateCommand,
+  "set-viewed": sessionSetViewedCommand,
+  navigate: sessionNavigateCommand,
+  branch: sessionBranchCommand,
+  switch: sessionSwitchCommand,
+  label: sessionLabelCommand,
+  fork: sessionForkCommand,
+  "name-self": sessionNameSelfCommand,
+  events: sessionEventsCommand,
   resolve: sessionResolveCommand,
   "submit-revision": sessionSubmitRevisionCommand,
 };
 
 export async function sessionCommand(argv: string[]): Promise<number> {
   const { positional, flags } = parseArgs(argv);
-  const verb = positional[0];
+  const primitive = positional[0];
   // --role agent (or collaborator) caps this connection to read + annotate; a
   // review-side agent passes it so the daemon rejects any escalation attempt.
+  // and --author binds the identity its comments, removals, and name carry
   const role = stringFlag(flags, "role") === "agent" ? "agent" : undefined;
-  const client = await DaemonClient.connect({ autostart: true, role });
+  const client = await DaemonClient.connect({
+    autostart: true,
+    role,
+    author: role === undefined ? undefined : stringFlag(flags, "author"),
+  });
 
   try {
-    const handler = verb !== undefined ? sessionVerbHandlers[verb] : undefined;
+    const handler = primitive !== undefined ? sessionVerbHandlers[primitive] : undefined;
 
     if (handler === undefined) {
       console.error(
-        "usage: cueloop session <create|get|list|wait|annotate|resolve|submit-revision> [flags]",
+        "usage: cueloop session <create|get|list|wait|annotate|remove|cut|restore|curate|set-viewed|navigate|branch|switch|label|fork|name-self|events|resolve|submit-revision> [flags]",
       );
 
       return 2;

package/src/share-command.test.ts

@@ -1,5 +1,11 @@
 import { describe, expect, mock, test } from "bun:test";
-import { SCHEMA_VERSION, type Annotation, type ReviewSession } from "@cueloop/schema";
+import {
+  appendEntry,
+  historyFromLinear,
+  SCHEMA_VERSION,
+  type Annotation,
+  type ReviewSession,
+} from "@cueloop/schema";
 import type { SessionClient } from "@cueloop/daemon/client";
 import { pullSession, shareSession, type PullDeps, type ShareDeps } from "./share-command";
 
@@ -30,11 +36,34 @@ function annotationFixture(id: string, author?: string): Annotation {
   return author ? { ...base, author } : base;
 }
 
-/** A SessionClient that answers get/list from a fixed list and records the share/merge verbs. */
+const unimplemented = (member: string) => () =>
+  Promise.reject(new Error(`fakeClient does not implement ${member}`));
+
+/** A SessionClient that answers get/list from a fixed list and records the share/merge primitives. */
 function fakeClient(sessions: ReviewSession[]): SessionClient {
   return {
+    onEvent: () => () => {},
+    subscribe: async () => {},
     sessionGet: async (id: string) => sessions.find((session) => session.id === id)!,
     sessionList: async () => sessions,
+    sessionAnnotate: unimplemented("sessionAnnotate"),
+    sessionRemoveAnnotation: unimplemented("sessionRemoveAnnotation"),
+    sessionSetWorkingCopy: unimplemented("sessionSetWorkingCopy"),
+    sessionCutBlock: unimplemented("sessionCutBlock"),
+    sessionRestoreBlock: unimplemented("sessionRestoreBlock"),
+    sessionCurate: unimplemented("sessionCurate"),
+    sessionNavigate: unimplemented("sessionNavigate"),
+    sessionBranch: unimplemented("sessionBranch"),
+    sessionSwitch: unimplemented("sessionSwitch"),
+    sessionLabel: unimplemented("sessionLabel"),
+    sessionFork: mock(async (id: string) => {
+      const fork = { ...sessionFixture(`${id}_fork`), parentSessionId: id };
+
+      sessions.push(fork);
+
+      return fork;
+    }),
+    sessionSetViewed: unimplemented("sessionSetViewed"),
     sessionSetShareId: mock(async (id: string, shareId: string) => {
       const session = sessions.find((candidate) => candidate.id === id)!;
 
@@ -42,16 +71,30 @@ function fakeClient(sessions: ReviewSession[]): SessionClient {
 
       return session;
     }),
-    sessionMergeShared: mock(async (id: string, incoming: { annotations: Annotation[] }) => {
-      const session = sessions.find((candidate) => candidate.id === id)!;
-      const known = new Set(session.annotations.map((annotation) => annotation.id));
-
-      for (const annotation of incoming.annotations)
-        if (!known.has(annotation.id)) session.annotations.push(annotation);
-
-      return session;
-    }),
-  } as unknown as SessionClient;
+    sessionMergeShared: mock(
+      async (
+        id: string,
+        incoming: { annotations: Annotation[]; removals?: Array<{ annotationId: string }> },
+      ) => {
+        const session = sessions.find((candidate) => candidate.id === id)!;
+        const known = new Set(session.annotations.map((annotation) => annotation.id));
+
+        for (const annotation of incoming.annotations)
+          if (!known.has(annotation.id)) session.annotations.push(annotation);
+        const shelved = new Set((incoming.removals ?? []).map((removal) => removal.annotationId));
+
+        session.annotations = session.annotations.filter(
+          (annotation) => !shelved.has(annotation.id),
+        );
+
+        return session;
+      },
+    ),
+    sessionDelete: unimplemented("sessionDelete"),
+    sessionSetSelfName: unimplemented("sessionSetSelfName"),
+    sessionResolve: unimplemented("sessionResolve"),
+    close: () => {},
+  };
 }
 
 function depsSpy(overrides: Partial<ShareDeps> = {}): ShareDeps & { lines: string[] } {
@@ -143,6 +186,28 @@ describe(shareSession, () => {
     // Assert
     expect(client.sessionSetShareId).toHaveBeenCalledWith("ses_1", "p_abc123xy");
   });
+
+  test("--fork shares a fork of the session and leaves the original unshared", async () => {
+    // Arrange
+    const session = sessionFixture("ses_1");
+    const client = fakeClient([session]);
+    const deps = depsSpy();
+
+    // Act
+    const code = await shareSession(client, { sessionId: "ses_1", fork: true }, deps);
+
+    // Assert
+    expect(code).toBe(0);
+    expect(client.sessionFork).toHaveBeenCalledWith("ses_1");
+    expect(deps.publish).toHaveBeenCalledTimes(1);
+    expect(deps.publish).toHaveBeenCalledWith(
+      expect.objectContaining({ id: "ses_1_fork", parentSessionId: "ses_1" }),
+      expect.anything(),
+    );
+    expect(client.sessionSetShareId).toHaveBeenCalledWith("ses_1_fork", "p_abc123xy");
+    expect(session.shareId).toBeUndefined();
+    expect(deps.lines[0]).toBe("forked ses_1 as ses_1_fork");
+  });
 });
 
 function pullDepsSpy(remote: ReviewSession): PullDeps & { lines: string[] } {
@@ -208,6 +273,34 @@ describe(pullSession, () => {
     expect(deps.lines).toEqual(["no new annotations"]);
   });
 
+  test("counts only the new notes when a pull also carries a removal", async () => {
+    // Arrange: the owner holds one collaborator note; the share brings a new note and removes the old one
+    const local = sessionFixture("ses_1", {
+      shareId: "p_abc123xy",
+      annotations: [annotationFixture("gone", "SHA256:mate")],
+    });
+    const remote = sessionFixture("ses_1", {
+      annotations: [
+        annotationFixture("gone", "SHA256:mate"),
+        annotationFixture("fresh", "SHA256:mate"),
+      ],
+    });
+
+    remote.history = appendEntry(historyFromLinear(remote), {
+      id: "e_rm",
+      type: "comment-removed",
+      annotationId: "gone",
+      createdAt: "2026-02-02T00:00:00.000Z",
+    }).history;
+    const deps = pullDepsSpy(remote);
+
+    // Act
+    await pullSession(fakeClient([local]), { sessionId: "ses_1" }, deps);
+
+    // Assert: one note is genuinely new, so a plain length difference (0) would be wrong
+    expect(deps.lines).toEqual(["pulled 1 new annotation"]);
+  });
+
   test("refuses to pull a plan that was never shared", async () => {
     // Arrange
     const deps = pullDepsSpy(sessionFixture("ses_1"));

package/src/share-command.ts

@@ -8,7 +8,7 @@
 
 import { DaemonClient, type SessionClient } from "@cueloop/daemon/client";
 import {
-  collaboratorAnnotations,
+  mergeFromShare,
   publishShare,
   pullShare,
   shareIdFromLine,
@@ -19,6 +19,8 @@ import type { ReviewSession } from "@cueloop/schema";
 
 export interface ShareParams {
   sessionId?: string;
+  /** Fork the session first and share the fork: one artifact to two people, with separate discussions. */
+  fork?: boolean;
   host?: string;
   port?: number;
   home?: string;
@@ -71,17 +73,19 @@ export async function shareSession(
   params: ShareParams,
   deps: ShareDeps,
 ): Promise<number> {
-  const session = await pickSession(client, params.sessionId);
+  const picked = await pickSession(client, params.sessionId);
 
-  if (!session) {
+  if (!picked) {
     deps.out("no plan to share - open a review first");
 
     return 1;
   }
+  const session = params.fork ? await client.sessionFork(picked.id) : picked;
   const { line, copied } = await deps.publish(session, { host: params.host, port: params.port });
   const shareId = shareIdFromLine(line);
 
   if (shareId) await client.sessionSetShareId(session.id, shareId);
+  if (params.fork) deps.out(`forked ${picked.id} as ${session.id}`);
   deps.out(copied ? `share link copied - ${line}` : line);
 
   return 0;
@@ -105,12 +109,10 @@ export async function pullSession(
     return 1;
   }
   const remote = await deps.pull(session.shareId!, { host: params.host, port: params.port });
-  const before = session.annotations.length;
-  const merged = await client.sessionMergeShared(session.id, {
-    annotations: collaboratorAnnotations(remote),
-    participants: remote.participants,
-  });
-  const added = merged.annotations.length - before;
+  const before = new Set(session.annotations.map((annotation) => annotation.id));
+  const merged = await client.sessionMergeShared(session.id, mergeFromShare(remote));
+  // count notes that were not here before, so a pull carrying removals never miscounts
+  const added = merged.annotations.filter((annotation) => !before.has(annotation.id)).length;
 
   deps.out(
     added > 0 ? `pulled ${added} new annotation${added === 1 ? "" : "s"}` : "no new annotations",