cueloop 0.1.0-alpha.4 → 0.1.0-alpha.41

package/src/open-target.ts

@@ -0,0 +1,117 @@
+/**
+ * Verb-first review-open resolution: turn a verb (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.
+ *
+ * Rules, in order:
+ *   - no selector opens the latest pending session in scope (most recent
+ *     createdAt, verdict still open) - the `--latest` default;
+ *   - a selector that exactly equals a session id opens that session, pending
+ *     or resolved;
+ *   - 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
+ * 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`
+ * 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.
+ */
+export function isPlanReview(session: ReviewSession): boolean {
+  return session.artifact.type === "plan";
+}
+export function isDiffReview(session: ReviewSession): boolean {
+  return session.artifact.type === "diff" && session.artifact.meta.pr === undefined;
+}
+export function isPrReview(session: ReviewSession): boolean {
+  return session.artifact.type === "diff" && session.artifact.meta.pr !== undefined;
+}
+
+/** Session ids are minted with this prefix; the id-vs-title split lives here. */
+export function isSessionId(value: string): boolean {
+  return value.startsWith("ses_");
+}
+
+export interface OpenTargetQuery {
+  /** Only sessions this predicate accepts are eligible - the verb's artifact scope. */
+  match: (session: ReviewSession) => boolean;
+  /** Positional id-or-title selector; absent means "latest pending". */
+  selector?: string;
+}
+
+export type OpenTarget =
+  | { kind: "session"; sessionId: string }
+  | { kind: "no-pending" }
+  | { kind: "no-match"; selector: string }
+  | { kind: "ambiguous"; selector: string; titles: string[] };
+
+/** Most-recent-first, so the head of a sorted list is always the latest. */
+function newestFirst(left: ReviewSession, right: ReviewSession): number {
+  return right.createdAt.localeCompare(left.createdAt);
+}
+
+export function resolveOpenTarget(sessions: ReviewSession[], query: OpenTargetQuery): OpenTarget {
+  const scoped = sessions.filter(query.match);
+
+  if (query.selector === undefined) {
+    const latestPending = scoped
+      .filter((candidate) => candidate.status === "pending")
+      .sort(newestFirst)[0];
+    return latestPending
+      ? { kind: "session", sessionId: latestPending.id }
+      : { kind: "no-pending" };
+  }
+
+  const selector = query.selector;
+  const byId = scoped.find((candidate) => candidate.id === selector);
+  if (byId) return { kind: "session", sessionId: byId.id };
+
+  const loweredSelector = selector.toLowerCase();
+  const titled = scoped.filter((candidate) => (candidate.artifact.meta.title ?? "").length > 0);
+
+  const exactTitle = titled
+    .filter((candidate) => candidate.artifact.meta.title!.toLowerCase() === loweredSelector)
+    .sort(newestFirst)[0];
+  if (exactTitle) return { kind: "session", sessionId: exactTitle.id };
+
+  const substringMatches = titled
+    .filter((candidate) => candidate.artifact.meta.title!.toLowerCase().includes(loweredSelector))
+    .sort(newestFirst);
+  if (substringMatches.length === 1) return { kind: "session", sessionId: substringMatches[0]!.id };
+  if (substringMatches.length === 0) return { kind: "no-match", selector };
+  return {
+    kind: "ambiguous",
+    selector,
+    titles: substringMatches.map((candidate) => candidate.artifact.meta.title!),
+  };
+}
+
+/**
+ * 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",
+ * "diff", "PR"). The "session" outcome has no message - the caller opens it.
+ */
+export function openTargetMessage(
+  label: string,
+  target: Exclude<OpenTarget, { kind: "session" }>,
+): string {
+  switch (target.kind) {
+    case "no-pending":
+      return `no pending ${label} review - nothing to open`;
+    case "no-match":
+      return `no ${label} review matches "${target.selector}" - nothing to open`;
+    case "ambiguous":
+      return [
+        `"${target.selector}" matches several ${label} reviews - name one:`,
+        ...target.titles.map((title) => `  - ${title}`),
+      ].join("\n");
+  }
+}

package/src/pr.ts

@@ -1,5 +1,5 @@
 /**
- * PR review entry (#18): `cueloop review <pr>` fetches the PR diff through the
+ * PR review entry: `cueloop review <pr>` fetches the PR diff through the
  * user's `gh` CLI (auth fully delegated), opens a diff session, and posts the
  * verdict back to the PR as a real review when the session resolves.
  * `cueloop review-post <session-id> <pr>` is the non-interactive post-back
@@ -8,8 +8,8 @@
 
 import type { ReviewSession, VerdictKind } from "@cueloop/schema";
 import { DaemonClient } from "@cueloop/daemon/client";
+import { openReview } from "@cueloop/daemon/review";
 import { parseArgs } from "./args";
-import { resolveWorkspace } from "./workspace";
 
 /** The gh binary is injectable so tests can stub it. */
 function ghBin(): string {
@@ -55,13 +55,16 @@ export async function reviewCommand(argv: string[]): Promise<number> {
     console.error(`PR ${pr} has an empty diff - nothing to review`);
     return 1;
   }
-  const workspace = await resolveWorkspace();
   const client = await DaemonClient.connect({ autostart: true });
-  const session = await client.sessionCreate(workspace, {
+  // A PR diff is a partial patch with no full file contents, so no `files` here;
+  // hunk curation stays disabled for PR reviews (see diff-hunk-curate.ts).
+  const review = await openReview(client, {
     type: "diff",
     content: diff.stdout,
-    meta: { title: `PR ${pr}`, pr, cwd: process.cwd() },
+    title: `PR ${pr}`,
+    pr,
   });
+  const session = review.session;
   client.close();
 
   if (flags["no-tui"]) {
@@ -108,7 +111,14 @@ async function getSession(id: string): Promise<ReviewSession> {
 /** Post the resolved session's verdict to the PR: feedback.md is the review body. */
 async function postVerdict(session: ReviewSession, pr: string): Promise<number> {
   const verdict = session.verdict!;
-  const result = await gh(["pr", "review", pr, VERDICT_FLAG[verdict.kind], "--body", verdict.feedback]);
+  const result = await gh([
+    "pr",
+    "review",
+    pr,
+    VERDICT_FLAG[verdict.kind],
+    "--body",
+    verdict.feedback,
+  ]);
   if (result.code !== 0) {
     console.error(result.stderr.trim() || `gh pr review ${pr} failed (exit ${result.code})`);
     return 1;

package/src/session-commands.ts

@@ -0,0 +1,153 @@
+/**
+ * `cueloop session *` - mirrors the daemon socket API 1:1. One surface,
+ * three consumers: agent adapters, the dev loop, and integrations. Output is
+ * JSON on stdout; exit code 0 unless the daemon returned an error.
+ */
+
+import { newAnnotationId, type ArtifactType, type VerdictKind } from "@cueloop/schema";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { openHerdrPaneForReview } from "@cueloop/daemon/herdr-pane";
+import { openReview, verdictResponse, type ReviewNote } from "@cueloop/daemon/review";
+import { loadConfig, quickActionBody, resolveQuickAction } from "@cueloop/client/config";
+import { parseArgs, stringFlag } from "./args";
+
+async function readStdin(): Promise<string> {
+  return await new Response(Bun.stdin.stream()).text();
+}
+
+function out(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export async function sessionCommand(argv: string[]): Promise<number> {
+  const { positional, flags } = parseArgs(argv);
+  const verb = 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.
+  const role = stringFlag(flags, "role") === "agent" ? "agent" : undefined;
+  const client = await DaemonClient.connect({ autostart: true, role });
+  try {
+    switch (verb) {
+      case "create": {
+        const contentFile = stringFlag(flags, "content-file");
+        const content = contentFile ? await Bun.file(contentFile).text() : await readStdin();
+        // 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[])
+          : undefined;
+        const review = await openReview(client, {
+          type: (stringFlag(flags, "type") ?? "plan") as ArtifactType,
+          content,
+          cwd: stringFlag(flags, "cwd"),
+          agent: stringFlag(flags, "agent"),
+          agentSessionId: stringFlag(flags, "agent-session-id"),
+          planPath: stringFlag(flags, "plan-path"),
+          title: stringFlag(flags, "title"),
+          notes,
+        });
+        // herdr auto-open: render the review in a tab (no-op outside herdr).
+        await openHerdrPaneForReview(review.session, client);
+        out(review.session);
+        return 0;
+      }
+      case "get": {
+        out(await client.sessionGet(required(positional[1], "session id")));
+        return 0;
+      }
+      case "list": {
+        const status = stringFlag(flags, "status") as "pending" | "resolved" | undefined;
+        out(await client.sessionList(status ? { status } : undefined));
+        return 0;
+      }
+      case "wait": {
+        const id = required(positional[1], "session id");
+        const timeoutMs = Number(stringFlag(flags, "timeout-ms") ?? "60000");
+        const session = await client.sessionWait(id, timeoutMs);
+        if (session === null) {
+          out({ status: "pending" });
+          return 0;
+        }
+        const { allow, feedback } = verdictResponse(session);
+        out({ status: "resolved", allow, verdict: session.verdict!.kind, feedback });
+        return 0;
+      }
+      case "annotate": {
+        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);
+        out(
+          await client.sessionAnnotate(
+            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"),
+          ),
+        );
+        return 0;
+      }
+      case "resolve": {
+        const id = required(positional[1], "session id");
+        const kind = required(stringFlag(flags, "verdict"), "--verdict") as VerdictKind;
+        out(await client.sessionResolve(id, kind, stringFlag(flags, "summary") ?? ""));
+        return 0;
+      }
+      case "submit-revision": {
+        const id = required(positional[1], "session id");
+        const contentFile = stringFlag(flags, "content-file");
+        const content = contentFile ? await Bun.file(contentFile).text() : await readStdin();
+        // --addressed a_1,a_2 - the annotation ids this revision acted on
+        const addressed = (stringFlag(flags, "addressed") ?? "")
+          .split(",")
+          .map((annotationId) => annotationId.trim())
+          .filter(Boolean);
+        out(await client.sessionSubmitRevision(id, content, addressed));
+        return 0;
+      }
+      default:
+        console.error(
+          "usage: cueloop session <create|get|list|wait|annotate|resolve|submit-revision> [flags]",
+        );
+        return 2;
+    }
+  } finally {
+    client.close();
+  }
+}
+
+function required<T>(value: T | undefined, description: string): T {
+  if (value === undefined) throw new Error(`missing ${description}`);
+  return value;
+}
+
+/**
+ * The annotation body: an explicit `--body`, else the `--action <index|name>`
+ * quick-action expanded through the shared vocabulary. The vocabulary is loaded
+ * from the reviewed session's own repo, not the caller's cwd, so an agent
+ * annotating from elsewhere still sees that session's actions.
+ */
+async function annotateBody(
+  flags: Record<string, string | boolean>,
+  client: DaemonClient,
+  id: string,
+): Promise<string> {
+  const explicit = stringFlag(flags, "body");
+  if (explicit !== undefined) return explicit;
+  const actionRef = stringFlag(flags, "action");
+  if (actionRef === undefined) return "";
+  const session = await client.sessionGet(id);
+  const actions = loadConfig({ repoRoot: session.workspace.repoRoot }).actions;
+  const action = resolveQuickAction(actions, actionRef);
+  if (!action) throw new Error(`no quick action ${actionRef} - see: cueloop actions list`);
+  return quickActionBody(action);
+}

package/src/share-command.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, mock, test } from "bun:test";
+import { 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";
+
+function sessionFixture(id: string, overrides: Partial<ReviewSession> = {}): ReviewSession {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id,
+    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 annotationFixture(id: string, author?: string): Annotation {
+  const base: Annotation = {
+    id,
+    kind: "comment",
+    anchor: { quote: "Plan", prefix: "", suffix: "" },
+    body: "note",
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+  return author ? { ...base, author } : base;
+}
+
+/** A SessionClient that answers get/list from a fixed list and records the share/merge verbs. */
+function fakeClient(sessions: ReviewSession[]): SessionClient {
+  return {
+    sessionGet: async (id: string) => sessions.find((session) => session.id === id)!,
+    sessionList: async () => sessions,
+    sessionSetShareId: mock(async (id: string, shareId: string) => {
+      const session = sessions.find((candidate) => candidate.id === id)!;
+      session.shareId = shareId;
+      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;
+}
+
+function depsSpy(overrides: Partial<ShareDeps> = {}): ShareDeps & { lines: string[] } {
+  const lines: string[] = [];
+  return {
+    publish: mock(async () => ({ line: "ssh p_abc123xy@cueloop.dev", copied: true })),
+    out: (message: string) => void lines.push(message),
+    lines,
+    ...overrides,
+  };
+}
+
+describe(shareSession, () => {
+  test("publishes the named session and reports the copied ssh line", async () => {
+    // Arrange
+    const publish = mock(
+      async (session: ReviewSession) => (
+        expect(session.id).toBe("ses_2"),
+        { line: "ssh p_abc123xy@cueloop.dev", copied: true }
+      ),
+    );
+    const deps = depsSpy({ publish });
+
+    // Act
+    const code = await shareSession(
+      fakeClient([sessionFixture("ses_1"), sessionFixture("ses_2")]),
+      { sessionId: "ses_2" },
+      deps,
+    );
+
+    // Assert
+    expect(code).toBe(0);
+    expect(deps.lines).toEqual(["share link copied - ssh p_abc123xy@cueloop.dev"]);
+  });
+
+  test("without an id, shares the most recent session", async () => {
+    // Arrange
+    const publish = mock(
+      async (session: ReviewSession) => (
+        expect(session.id).toBe("ses_2"),
+        { line: "ssh p_zzzzzzzz@cueloop.dev", copied: true }
+      ),
+    );
+    const deps = depsSpy({ publish });
+
+    // Act
+    await shareSession(fakeClient([sessionFixture("ses_1"), sessionFixture("ses_2")]), {}, deps);
+
+    // Assert
+    expect(deps.publish).toHaveBeenCalledTimes(1);
+  });
+
+  test("prints the bare line when the clipboard is unavailable", async () => {
+    // Arrange
+    const deps = depsSpy({
+      publish: mock(async () => ({ line: "ssh p_abc123xy@cueloop.dev", copied: false })),
+    });
+
+    // Act
+    await shareSession(fakeClient([sessionFixture("ses_1")]), { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(deps.lines).toEqual(["ssh p_abc123xy@cueloop.dev"]);
+  });
+
+  test("reports nothing to share when the inbox is empty", async () => {
+    // Arrange
+    const deps = depsSpy();
+
+    // Act
+    const code = await shareSession(fakeClient([]), {}, deps);
+
+    // Assert
+    expect(code).toBe(1);
+    expect(deps.lines[0]).toContain("no plan to share");
+    expect(deps.publish).not.toHaveBeenCalled();
+  });
+
+  test("stamps the share id on the session so a later pull can find it", async () => {
+    // Arrange
+    const session = sessionFixture("ses_1");
+    const client = fakeClient([session]);
+    const deps = depsSpy();
+
+    // Act
+    await shareSession(client, { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(client.sessionSetShareId).toHaveBeenCalledWith("ses_1", "p_abc123xy");
+  });
+});
+
+function pullDepsSpy(remote: ReviewSession): PullDeps & { lines: string[] } {
+  const lines: string[] = [];
+  return {
+    pull: mock(async () => remote),
+    out: (message: string) => void lines.push(message),
+    lines,
+  };
+}
+
+describe(pullSession, () => {
+  test("unions collaborator notes in, ignoring the planner's own unauthored notes", async () => {
+    // Arrange - the planner's own note carries no author; the collaborator's does
+    const local = sessionFixture("ses_1", {
+      shareId: "p_abc123xy",
+      annotations: [annotationFixture("mine")],
+    });
+    const client = fakeClient([local]);
+    const remote = sessionFixture("ses_1", {
+      annotations: [annotationFixture("mine"), annotationFixture("theirs", "SHA256:mate")],
+    });
+    const deps = pullDepsSpy(remote);
+
+    // Act
+    const code = await pullSession(client, { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(code).toBe(0);
+    expect(deps.pull).toHaveBeenCalledWith("p_abc123xy", { host: undefined, port: undefined });
+    expect(local.annotations.map((annotation) => annotation.id)).toEqual(["mine", "theirs"]);
+    expect(deps.lines).toEqual(["pulled 1 new annotation"]);
+  });
+
+  test("does not resurrect a note the planner deleted locally after sharing", async () => {
+    // Arrange - the planner deleted "mine" locally; the share blob still carries it, unauthored
+    const local = sessionFixture("ses_1", { shareId: "p_abc123xy", annotations: [] });
+    const deps = pullDepsSpy(sessionFixture("ses_1", { annotations: [annotationFixture("mine")] }));
+
+    // Act
+    await pullSession(fakeClient([local]), { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(local.annotations).toEqual([]);
+    expect(deps.lines).toEqual(["no new annotations"]);
+  });
+
+  test("reports when nothing new came back", async () => {
+    // Arrange
+    const local = sessionFixture("ses_1", {
+      shareId: "p_abc123xy",
+      annotations: [annotationFixture("theirs", "SHA256:mate")],
+    });
+    const deps = pullDepsSpy(
+      sessionFixture("ses_1", { annotations: [annotationFixture("theirs", "SHA256:mate")] }),
+    );
+
+    // Act
+    await pullSession(fakeClient([local]), { sessionId: "ses_1" }, deps);
+
+    // Assert
+    expect(deps.lines).toEqual(["no new annotations"]);
+  });
+
+  test("refuses to pull a plan that was never shared", async () => {
+    // Arrange
+    const deps = pullDepsSpy(sessionFixture("ses_1"));
+
+    // Act
+    const code = await pullSession(
+      fakeClient([sessionFixture("ses_1")]),
+      { sessionId: "ses_1" },
+      deps,
+    );
+
+    // Assert
+    expect(code).toBe(1);
+    expect(deps.lines[0]).toContain("no shared plan");
+    expect(deps.pull).not.toHaveBeenCalled();
+  });
+});

package/src/share-command.ts

@@ -0,0 +1,133 @@
+/**
+ * `cueloop share [session-id]` - hand a plan to a teammate as one SSH line.
+ * This side just picks the session and delegates to the shared `publishShare`
+ * transport (the same one the in-TUI Share button uses); the gateway seals and
+ * stores. The transport and output are injected so the orchestration is
+ * testable without a live gateway.
+ */
+
+import { DaemonClient, type SessionClient } from "@cueloop/daemon/client";
+import {
+  collaboratorAnnotations,
+  publishShare,
+  pullShare,
+  shareIdFromLine,
+  type ShareResult,
+  type ShareTarget,
+} from "@cueloop/client";
+import type { ReviewSession } from "@cueloop/schema";
+
+export interface ShareParams {
+  sessionId?: string;
+  host?: string;
+  port?: number;
+  home?: string;
+}
+
+export interface ShareDeps {
+  publish: (session: ReviewSession, target: ShareTarget) => Promise<ShareResult>;
+  out: (message: string) => void;
+}
+
+export interface PullDeps {
+  pull: (shareId: string, target: ShareTarget) => Promise<ReviewSession>;
+  out: (message: string) => void;
+}
+
+const defaultDeps: ShareDeps = { publish: publishShare, out: (message) => console.log(message) };
+const defaultPullDeps: PullDeps = { pull: pullShare, out: (message) => console.log(message) };
+
+/** Connect to the local daemon, then share the chosen session. */
+export async function shareCommand(
+  params: ShareParams,
+  deps: ShareDeps = defaultDeps,
+): Promise<number> {
+  const client = await DaemonClient.connect({ home: params.home, autostart: true });
+  try {
+    return await shareSession(client, params, deps);
+  } finally {
+    client.close();
+  }
+}
+
+/** Connect to the local daemon, then pull collaborator notes for the plan. */
+export async function sharePullCommand(
+  params: ShareParams,
+  deps: PullDeps = defaultPullDeps,
+): Promise<number> {
+  const client = await DaemonClient.connect({ home: params.home, autostart: true });
+  try {
+    return await pullSession(client, params, deps);
+  } finally {
+    client.close();
+  }
+}
+
+/** The share orchestration, over any SessionClient - the seam the tests drive. */
+export async function shareSession(
+  client: SessionClient,
+  params: ShareParams,
+  deps: ShareDeps,
+): Promise<number> {
+  const session = await pickSession(client, params.sessionId);
+  if (!session) {
+    deps.out("no plan to share - open a review first");
+    return 1;
+  }
+  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);
+  deps.out(copied ? `share link copied - ${line}` : line);
+  return 0;
+}
+
+/**
+ * Pull the share's current session and union its annotations into the local
+ * plan. Union-by-id keeps the planner's own notes; only collaborators' new
+ * ones land. The gateway lets only the fingerprint that shared it pull.
+ */
+export async function pullSession(
+  client: SessionClient,
+  params: ShareParams,
+  deps: PullDeps,
+): Promise<number> {
+  const session = await pickSharedSession(client, params.sessionId);
+  if (!session) {
+    deps.out("no shared plan to pull - run `cueloop share` first");
+    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;
+  deps.out(
+    added > 0 ? `pulled ${added} new annotation${added === 1 ? "" : "s"}` : "no new annotations",
+  );
+  return 0;
+}
+
+/** The named session, or the most recent one when no id is given. */
+async function pickSession(
+  client: SessionClient,
+  sessionId?: string,
+): Promise<ReviewSession | null> {
+  if (sessionId) return client.sessionGet(sessionId);
+  const sessions = await client.sessionList();
+  return sessions.at(-1) ?? null;
+}
+
+/** The named session (if shared), or the most recent shared one. */
+async function pickSharedSession(
+  client: SessionClient,
+  sessionId?: string,
+): Promise<ReviewSession | null> {
+  if (sessionId) {
+    const session = await client.sessionGet(sessionId);
+    return session.shareId ? session : null;
+  }
+  const sessions = await client.sessionList();
+  return sessions.filter((session) => session.shareId).at(-1) ?? null;
+}

package/src/version.ts

@@ -0,0 +1,5 @@
+/** The published CLI version, read from the package manifest at build time. */
+
+import manifest from "../package.json" with { type: "json" };
+
+export const CLI_VERSION: string = manifest.version;