cueloop 0.1.0-alpha.64 → 0.1.0-alpha.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.64",
+  "version": "0.1.0-alpha.66",
   "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,10 @@
     "build:binary": "bun build --compile --external cpu-features ./src/main.ts --outfile dist/cueloop"
   },
   "dependencies": {
-    "@cueloop/adapters": "0.1.0-alpha.64",
-    "@cueloop/client": "0.1.0-alpha.64",
-    "@cueloop/daemon": "0.1.0-alpha.64",
-    "@cueloop/schema": "0.1.0-alpha.64",
+    "@cueloop/adapters": "0.1.0-alpha.66",
+    "@cueloop/client": "0.1.0-alpha.66",
+    "@cueloop/daemon": "0.1.0-alpha.66",
+    "@cueloop/schema": "0.1.0-alpha.66",
     "valibot": "^1.4.2"
   },
   "engines": {

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/dev-command.ts

@@ -0,0 +1,85 @@
+/**
+ * `cueloop dev`: open the TUI against an isolated dev home seeded once with a
+ * plan and a diff under this repo's project plus a standalone reply thread, so
+ * the Projects and Threads sidebar and the thread view are populated without a
+ * live agent. It never touches the real ~/.cueloop home.
+ */
+
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { resolveWorkspace } from "@cueloop/daemon/review";
+
+const SEED_PLAN = `# Read the repository
+
+A seeded plan so \`cueloop dev\` always has a thread to open.
+
+## Steps
+- open the thread view
+- move the cursor into the agent's text
+- type to leave a comment
+`;
+
+const SEED_REPLY = `A standalone thought, not tied to any repository.
+
+It lands under Threads in the sidebar rather than a project.
+`;
+
+const SEED_DIFF_PATH = "packages/client/src/theme.ts";
+const SEED_DIFF_OLD = '  accent: "#f5a3a3",\n';
+const SEED_DIFF_NEW = '  accent: "#cba6f7",\n';
+const SEED_DIFF = `diff --git a/${SEED_DIFF_PATH} b/${SEED_DIFF_PATH}
+--- a/${SEED_DIFF_PATH}
++++ b/${SEED_DIFF_PATH}
+@@ -1 +1 @@
+-${SEED_DIFF_OLD.trimEnd()}
++${SEED_DIFF_NEW.trimEnd()}
+`;
+
+async function seedDevSessions(client: DaemonClient): Promise<void> {
+  // the current repo carries a root commit, so its threads gather under a project
+  const project = await resolveWorkspace(process.cwd());
+  // a non-repo directory has no root commit, so its thread stays standalone
+  const standalone = await resolveWorkspace(tmpdir());
+
+  await client.sessionCreate(project, {
+    type: "plan",
+    content: SEED_PLAN,
+    meta: { title: "Read the repository" },
+  });
+  await client.sessionCreate(project, {
+    type: "diff",
+    content: SEED_DIFF,
+    meta: { title: "Review the accent change" },
+    files: [
+      {
+        path: SEED_DIFF_PATH,
+        oldContents: SEED_DIFF_OLD,
+        newContents: SEED_DIFF_NEW,
+        status: "modified",
+      },
+    ],
+  });
+  await client.sessionCreate(standalone, {
+    type: "reply",
+    content: SEED_REPLY,
+    meta: { title: "A standalone thought" },
+  });
+}
+
+/** `cueloop dev`: seed an isolated dev home once, then open the TUI on it. */
+export async function devCommand(): Promise<number> {
+  process.env.CUELOOP_HOME ??= join(homedir(), ".cueloop-dev");
+
+  const client = await DaemonClient.connect({ autostart: true });
+  try {
+    const existing = await client.sessionList();
+    if (existing.length === 0) await seedDevSessions(client);
+  } finally {
+    client.close();
+  }
+
+  const { runClient } = await import("@cueloop/client");
+
+  return runClient({});
+}

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,7 +93,7 @@ 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>;
@@ -116,6 +116,7 @@ const commandHandlers: CommandHandlers = {
   refine: async (rest) => (await import("./refine-command")).refineCommand(rest),
   review: (rest) => reviewEntry(rest),
   "review-post": async (rest) => (await import("./pr")).reviewPostCommand(rest),
+  dev: async () => (await import("./dev-command")).devCommand(),
 };
 
 const versionAliases = new Set(["-v", "--version", "version"]);
@@ -143,7 +144,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.
@@ -155,7 +156,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).
  */
@@ -340,12 +341,13 @@ 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)",
       "  cueloop review-post <id> <pr>    post a resolved session's verdict back to the PR",
       "  cueloop daemon                   run the daemon in the foreground",
+      "  cueloop dev                      open the TUI on an isolated home seeded with example threads",
       "",
       "  cueloop -v, --version            print the installed version",
       "  cueloop -h, --help               print this help",

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,7 +4,13 @@
  * JSON on stdout; exit code 0 unless the daemon returned an error.
  */
 
-import { ARTIFACT_TYPES, isArtifactType, newAnnotationId } 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";
@@ -93,37 +99,242 @@ 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.sessionRestoreBlock(
+      id,
+      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.sessionAnnotate(
+    await client.sessionNavigate(
       id,
-      {
-        id: stringFlag(flags, "annotation-id") ?? newAnnotationId(),
-        kind: stringFlag(flags, "kind") ?? "comment",
-        anchor: {
-          quote,
-          prefix: stringFlag(flags, "prefix") ?? "",
-          suffix: stringFlag(flags, "suffix") ?? "",
-        },
-        body,
-        author,
-      },
-      stringFlag(flags, "author-name"),
+      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,
@@ -157,7 +368,7 @@ async function sessionSubmitRevisionCommand({
 }
 
 interface SessionVerbHandlers {
-  [verb: string]: SessionVerbHandler;
+  [primitive: string]: SessionVerbHandler;
 }
 
 const sessionVerbHandlers: SessionVerbHandlers = {
@@ -166,24 +377,41 @@ const sessionVerbHandlers: SessionVerbHandlers = {
   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";
 
@@ -33,7 +39,7 @@ function annotationFixture(id: string, author?: string): Annotation {
 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 verbs. */
+/** A SessionClient that answers get/list from a fixed list and records the share/merge primitives. */
 function fakeClient(sessions: ReviewSession[]): SessionClient {
   return {
     onEvent: () => () => {},
@@ -43,6 +49,20 @@ function fakeClient(sessions: ReviewSession[]): SessionClient {
     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)!;
@@ -51,15 +71,25 @@ 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;
-    }),
+    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"),
@@ -156,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[] } {
@@ -221,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",