cueloop 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/main.ts

@@ -1,105 +1,319 @@
 #!/usr/bin/env bun
 /**
- * cueloop entry points (#18): `cueloop` opens the TUI on the inbox,
- * `cueloop diff` reviews the working tree, `cueloop review <pr>` a PR,
- * `cueloop session *` mirrors the daemon API for agents and scripts,
- * `cueloop serve` shares a session over ssh (read-only observers),
- * `cueloop daemon` runs the daemon in the foreground.
+ * 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
+ * agents and scripts, `cueloop serve` shares a session over ssh (read-only
+ * observers), `cueloop daemon` runs the daemon in the foreground.
  */
 
-import { parseArgs, flagStr } from "./args";
-import { sessionCommand } from "./session-cmds";
-import { workingTreeDiff } from "./working-tree";
+import { basename, resolve } from "node:path";
+import { parseArgs, stringFlag, type ParsedArgs } from "./args";
+import {
+  isDiffReview,
+  isPlanReview,
+  isPrototypeReview,
+  isPrReview,
+  isReplyReview,
+  isSessionId,
+  openTargetMessage,
+  resolveOpenTarget,
+} from "./open-target";
+import { sessionCommand } from "./session-commands";
+import { CLI_VERSION } from "./version";
 import { DaemonClient } from "@cueloop/daemon/client";
+import { workingTreeDiff } from "@cueloop/daemon/working-tree";
+import type { Thread } from "@cueloop/schema";
 import { openReview, resolveWorkspace } from "@cueloop/daemon/review";
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
 
+async function daemonCommand(argv: string[]): Promise<number> {
+  const { DaemonServer } = await import("@cueloop/daemon");
+  // Explicit foreground never idle-exits; --autostart (a re-exec from the client)
+  // takes the normal idle-exit, matching the source main.ts entry.
+  const envIdle = process.env.CUELOOP_IDLE_EXIT_MS;
+  let idleExitMs: number | undefined = 0;
+
+  if (argv.includes("--autostart")) idleExitMs = envIdle ? Number(envIdle) : undefined;
+  const server = new DaemonServer({ idleExitMs });
+  const path = server.start();
+
+  if (path === null) {
+    console.error("a cueloop daemon already owns this home - nothing to do");
+
+    return 1;
+  }
+  console.log(`cueloop daemon (foreground) on ${path}`);
+  await new Promise(() => {}); // run until signalled
+
+  return 0;
+}
+
+async function serveEntry(rest: string[]): Promise<number> {
+  const { positional, flags } = parseArgs(rest);
+  const port = stringFlag(flags, "port");
+  const { serveClient } = await import("@cueloop/client");
+  const handle = await serveClient({
+    port: port !== undefined ? Number(port) : undefined,
+    host: stringFlag(flags, "host"),
+    sessionId: positional[0],
+  });
+
+  console.log(
+    [
+      "",
+      `observers join with:  ssh -p ${handle.port} ${handle.host === "0.0.0.0" || handle.host === "::" ? "<this-host>" : handle.host}`,
+      "",
+      "no passwords, no keys: anyone who can reach this address can watch.",
+      "share the address deliberately (SSH tunnel, tailnet). observers are",
+      "read-only; you stay the one writable controller via `cueloop` locally.",
+      "ctrl-c stops serving.",
+    ].join("\n"),
+  );
+  const stop = () => void handle.close().finally(() => process.exit(0));
+
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  await new Promise(() => {}); // serve until signalled
+
+  return 0;
+}
+
+async function shareEntry(rest: string[]): Promise<number> {
+  const { positional, flags } = parseArgs(rest);
+  const { shareCommand, sharePullCommand } = await import("./share-command");
+  const port = stringFlag(flags, "port");
+  const target = {
+    host: stringFlag(flags, "host"),
+    port: port !== undefined ? Number(port) : undefined,
+  };
+
+  if (positional[0] === "pull") return sharePullCommand({ ...target, sessionId: positional[1] });
+
+  return shareCommand({ ...target, sessionId: positional[0], fork: flags.fork === true });
+}
+
+type CommandHandler = (rest: string[]) => number | Promise<number>;
+
+interface CommandHandlers {
+  [command: string]: CommandHandler;
+}
+
+const commandHandlers: CommandHandlers = {
+  session: (rest) => sessionCommand(rest),
+  daemon: (rest) => daemonCommand(rest),
+  plan: (rest) => planCommand(rest),
+  reply: (rest) => replyCommand(rest),
+  diff: (rest) => diffCommand(rest),
+  prototype: (rest) => prototypeCommand(rest),
+  serve: (rest) => serveEntry(rest),
+  share: (rest) => shareEntry(rest),
+  wake: async (rest) => (await import("./wake-command")).wakeCommand(rest),
+  actions: async (rest) => (await import("./actions-command")).actionsCommand(rest),
+  refine: async (rest) => (await import("./refine-command")).refineCommand(rest),
+  update: async (rest) => (await import("./update-command")).updateCommand(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"]);
+const helpAliases = new Set(["-h", "--help", "help"]);
+
 async function main(): Promise<number> {
-  switch (cmd) {
-    case "session":
-      return sessionCommand(argv.slice(1));
-    case "daemon": {
-      const { DaemonServer } = await import("@cueloop/daemon");
-      const server = new DaemonServer({ idleExitMs: 0 });
-      const path = server.start();
-      if (path === null) {
-        console.error("a cueloop daemon already owns this home - nothing to do");
-        return 1;
-      }
-      console.log(`cueloop daemon (foreground) on ${path}`);
-      await new Promise(() => {}); // run until signalled
-      return 0;
-    }
-    case "diff": {
-      const workspace = await resolveWorkspace();
-      const diff = await workingTreeDiff();
-      if (!diff.trim()) {
-        console.error("working tree is clean - nothing to review");
-        return 1;
-      }
-      const client = await DaemonClient.connect({ autostart: true });
-      const review = await openReview(client, {
-        type: "diff",
-        content: diff,
-        workspace,
-        title: `working tree @ ${workspace.branch}`,
-      });
-      client.close();
-      return runTui(review.id);
-    }
-    case "serve": {
-      const { positional, flags } = parseArgs(argv.slice(1));
-      const port = flagStr(flags, "port");
-      const { serveClient } = await import("@cueloop/client");
-      const handle = await serveClient({
-        port: port !== undefined ? Number(port) : undefined,
-        host: flagStr(flags, "host"),
-        sessionId: positional[0],
-      });
-      console.log(
-        [
-          "",
-          `observers join with:  ssh -p ${handle.port} ${handle.host === "0.0.0.0" || handle.host === "::" ? "<this-host>" : handle.host}`,
-          "",
-          "no passwords, no keys: anyone who can reach this address can watch.",
-          "share the address deliberately (SSH tunnel, tailnet). observers are",
-          "read-only; you stay the one writable controller via `cueloop` locally.",
-          "ctrl-c stops serving.",
-        ].join("\n"),
-      );
-      const stop = () => void handle.close().finally(() => process.exit(0));
-      process.on("SIGINT", stop);
-      process.on("SIGTERM", stop);
-      await new Promise(() => {}); // serve until signalled
-      return 0;
-    }
-    case "review": {
-      const { reviewCommand } = await import("./pr");
-      return reviewCommand(argv.slice(1));
-    }
-    case "review-post": {
-      const { reviewPostCommand } = await import("./pr");
-      return reviewPostCommand(argv.slice(1));
-    }
-    case "--help":
-    case "help":
-      printHelp();
-      return 0;
-    case undefined:
-      return runTui();
-    default: {
-      // `cueloop <session-id>` opens the TUI on that session
-      if (cmd.startsWith("ses_")) return runTui(cmd);
-      printHelp();
-      return 2;
-    }
+  if (cmd === undefined) return runTui();
+  const handler = commandHandlers[cmd];
+
+  if (handler !== undefined) return handler(argv.slice(1));
+  if (versionAliases.has(cmd)) {
+    console.log(CLI_VERSION);
+
+    return 0;
+  }
+  if (helpAliases.has(cmd)) {
+    printHelp();
+
+    return 0;
   }
+  if (cmd.startsWith("ses_")) return runTui(cmd);
+  printHelp();
+
+  return 2;
+}
+
+/**
+ * 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.
+ */
+function openSelector(parsed: ParsedArgs): string | undefined {
+  return (
+    parsed.positional[0] ?? stringFlag(parsed.flags, "open") ?? stringFlag(parsed.flags, "latest")
+  );
+}
+
+/**
+ * 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).
+ */
+async function openReviewOfKind(
+  match: (session: Thread) => boolean,
+  label: string,
+  selector: string | undefined,
+  emptyMessage?: string,
+): Promise<number> {
+  const client = await DaemonClient.connect({ autostart: true });
+  let sessions: Thread[];
+
+  try {
+    sessions = await client.sessionList();
+  } finally {
+    client.close();
+  }
+  const target = resolveOpenTarget(sessions, { match, selector });
+
+  if (target.kind === "session") return runTui(target.sessionId);
+  if (target.kind === "no-pending" && emptyMessage !== undefined) {
+    console.error(emptyMessage);
+
+    return 1;
+  }
+  console.error(openTargetMessage(label, target));
+
+  return 1;
+}
+
+/** `cueloop plan [id|title]` - open the latest pending plan, or address one. */
+async function planCommand(argv: string[]): Promise<number> {
+  return openReviewOfKind(isPlanReview, "plan", openSelector(parseArgs(argv)));
+}
+
+/**
+ * `cueloop reply [id|title]` - open the latest pending reply review, or address
+ * one. A reply artifact is the agent's previous message, submitted for review
+ * by the /cueloop:reply skill; the opener is scope-only, like plan.
+ */
+async function replyCommand(argv: string[]): Promise<number> {
+  return openReviewOfKind(isReplyReview, "reply", openSelector(parseArgs(argv)));
+}
+
+/**
+ * `cueloop prototype <file.md>` creates a review of a component design doc
+ * (API / Composition / Callstack); an `.html` file instead creates the opt-in
+ * experimental pixel mockup. A selector or `--open`/`--latest` (or a bare call
+ * with no file) opens the latest pending prototype review instead.
+ */
+async function prototypeCommand(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  const selector = openSelector(parsed);
+  const wantsOpen = "open" in parsed.flags || "latest" in parsed.flags;
+  // a markdown design doc is the default; an .html entry is the opt-in pixel mockup
+  const isHtmlPrototype = selector?.endsWith(".html") ?? false;
+  const isMarkdownPrototype = selector?.endsWith(".md") || selector?.endsWith(".markdown") || false;
+  const looksLikeFile =
+    selector !== undefined && !isSessionId(selector) && (isHtmlPrototype || isMarkdownPrototype);
+
+  if (wantsOpen || !looksLikeFile)
+    return openReviewOfKind(isPrototypeReview, "prototype", selector);
+
+  const path = resolve(selector);
+  const content = await Bun.file(path)
+    .text()
+    .catch(() => undefined);
+
+  if (content === undefined) {
+    console.error(`prototype: cannot read ${path}`);
+
+    return 1;
+  }
+  const client = await DaemonClient.connect({ autostart: true });
+  const review = await openReview(client, {
+    type: "prototype",
+    content,
+    // only an HTML entry carries a prototypePath, the signal for the experimental pixel mode
+    prototypePath: isHtmlPrototype ? path : undefined,
+    title: basename(path),
+  });
+
+  client.close();
+
+  return runTui(review.id);
+}
+
+/**
+ * `cueloop diff` disambiguates create from open by intent:
+ *   - a selector (`cueloop diff <id|title>`) or an explicit `--open`/`--latest`
+ *     opens a pending diff review;
+ *   - otherwise a dirty working tree still creates a review as before;
+ *   - a clean working tree carries no create input, so it opens the latest
+ *     pending diff review instead of erroring.
+ */
+async function diffCommand(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  const selector = openSelector(parsed);
+  const wantsOpen = selector !== undefined || "open" in parsed.flags || "latest" in parsed.flags;
+
+  if (wantsOpen) return openReviewOfKind(isDiffReview, "diff", selector);
+
+  const workspace = await resolveWorkspace();
+  const diff = await workingTreeDiff();
+
+  if (!diff.patch.trim()) {
+    return openReviewOfKind(
+      isDiffReview,
+      "diff",
+      undefined,
+      "working tree is clean and no pending diff review - nothing to open",
+    );
+  }
+  const client = await DaemonClient.connect({ autostart: true });
+  const review = await openReview(client, {
+    type: "diff",
+    content: diff.patch,
+    files: diff.files,
+    workspace,
+    title: `working tree @ ${workspace.branch}`,
+  });
+
+  client.close();
+
+  return runTui(review.id);
+}
+
+/**
+ * `cueloop review` disambiguates create from open by intent:
+ *   - bare `cueloop review`, `--open`/`--latest`, or a `ses_*` selector opens a
+ *     pending PR review (a diff carrying a `pr` reference);
+ *   - any other positional is a PR reference and takes the create path in pr.ts.
+ */
+async function reviewEntry(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  const explicitOpen = "open" in parsed.flags || "latest" in parsed.flags;
+  const selector = openSelector(parsed);
+  const looksLikeSessionId = selector !== undefined && isSessionId(selector);
+  const wantsCreate = !explicitOpen && !looksLikeSessionId && selector !== undefined;
+
+  if (wantsCreate) {
+    const { reviewCommand } = await import("./pr");
+
+    return reviewCommand(argv);
+  }
+
+  return openReviewOfKind(
+    isPrReview,
+    "PR",
+    explicitOpen || looksLikeSessionId ? selector : undefined,
+  );
 }
 
 async function runTui(sessionId?: string): Promise<number> {
   const { runClient } = await import("@cueloop/client");
+
   return runClient({ sessionId });
 }
 
@@ -108,17 +322,42 @@ function printHelp(): void {
     [
       "cueloop - review surface for coding agents",
       "",
-      "usage:",
+      "usage: cueloop [command] [options]",
+      "",
+      "common commands:",
       "  cueloop                          open the inbox",
-      "  cueloop <session-id>             open one session",
-      "  cueloop diff                     review the working tree",
+      "  cueloop plan [id|title]          open the latest pending plan review (or one by id/title)",
+      "  cueloop reply [id|title]         open the latest pending reply review (the agent's previous message)",
+      "  cueloop diff [id|title]          review your working tree (untracked files included);",
+      "                                   with a clean tree, open the latest pending diff review",
       "  cueloop review <pr>              review a pull request (--no-tui prints the session)",
-      "  cueloop review-post <id> <pr>    post a resolved session's verdict back to the PR",
+      "  cueloop prototype <file.md>      review a component design doc (or open the latest by id/title)",
+      "",
+      "share:",
       "  cueloop serve [session-id]       share over ssh: observers are read-only,",
       "                                   you stay the controller (--port 2222, --host 127.0.0.1;",
       "                                   password-less - share the address deliberately)",
-      "  cueloop session <verb> [flags]   script the daemon (create|get|list|wait|annotate|resolve|submit-revision)",
+      "  cueloop share [session-id]       hand a plan to a teammate: copies one",
+      "                                   ssh line (--host cueloop.dev, --port 22)",
+      "  cueloop share pull [session-id]  pull a teammate's annotations back into the plan",
+      "",
+      "open a specific review:",
+      "  cueloop <session-id>             open one session",
+      "  cueloop review [id|title]        open the latest pending PR review (or one by id/title)",
+      "  cueloop <plan|diff|review> --latest  open the latest pending review of that type",
+      "",
+      "scripting:",
+      "  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 update [--dry-run]       update the installed cueloop binary (--dry-run reports the target only)",
+      "  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",
     ].join("\n"),
   );
 }

package/src/open-target.test.ts

@@ -0,0 +1,241 @@
+/** 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, Thread } from "@cueloop/schema";
+import {
+  isDiffReview,
+  isPlanReview,
+  isPrototypeReview,
+  isPrReview,
+  isReplyReview,
+  isSessionId,
+  openTargetMessage,
+  resolveOpenTarget,
+} from "./open-target";
+
+function session(overrides: {
+  id: string;
+  type?: ArtifactType;
+  title?: string;
+  status?: "pending" | "resolved";
+  createdAt?: string;
+  pr?: string;
+}): Thread {
+  return {
+    schemaVersion: "1",
+    id: overrides.id,
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: {
+      type: overrides.type ?? "plan",
+      content: "",
+      meta: { title: overrides.title, pr: overrides.pr },
+    },
+    revisions: [],
+    annotations: [],
+    verdict:
+      overrides.status === "resolved"
+        ? { kind: "approve", summary: "", feedback: "", resolvedAt: "" }
+        : null,
+    status: overrides.status ?? "pending",
+    createdAt: overrides.createdAt ?? "2026-01-01T00:00:00.000Z",
+  };
+}
+
+const isPlan = isPlanReview;
+
+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);
+  });
+
+  test("isDiffReview matches a plain diff but NOT a diff carrying meta.pr", () => {
+    expect(isDiffReview(session({ id: "ses_d", type: "diff" }))).toBe(true);
+    expect(isDiffReview(session({ id: "ses_pr", type: "diff", pr: "42" }))).toBe(false);
+    expect(isDiffReview(session({ id: "ses_p", type: "plan" }))).toBe(false);
+  });
+
+  test("isPrReview matches a diff carrying meta.pr, and only that", () => {
+    expect(isPrReview(session({ id: "ses_pr", type: "diff", pr: "42" }))).toBe(true);
+    expect(isPrReview(session({ id: "ses_d", type: "diff" }))).toBe(false);
+    expect(isPrReview(session({ id: "ses_p", type: "plan" }))).toBe(false);
+  });
+
+  test("isPrototypeReview matches only prototype artifacts", () => {
+    expect(isPrototypeReview(session({ id: "ses_x", type: "prototype" }))).toBe(true);
+    expect(isPrototypeReview(session({ id: "ses_p", type: "plan" }))).toBe(false);
+    expect(isPrototypeReview(session({ id: "ses_d", type: "diff" }))).toBe(false);
+  });
+
+  test("isReplyReview matches only reply artifacts, and never a plan", () => {
+    expect(isReplyReview(session({ id: "ses_r", type: "reply" }))).toBe(true);
+    expect(isReplyReview(session({ id: "ses_p", type: "plan" }))).toBe(false);
+    expect(isReplyReview(session({ id: "ses_d", type: "diff" }))).toBe(false);
+    expect(isPlanReview(session({ id: "ses_r", type: "reply" }))).toBe(false);
+  });
+
+  test("a PR review resolves under exactly one scope - never both diff and review", () => {
+    // Arrange
+    const prReview = session({ id: "ses_pr", type: "diff", pr: "42" });
+
+    // Assert
+    expect(isDiffReview(prReview)).toBe(false);
+    expect(isPrReview(prReview)).toBe(true);
+  });
+});
+
+describe("isSessionId", () => {
+  test("only the ses_ prefix reads as an id", () => {
+    expect(isSessionId("ses_abc")).toBe(true);
+    expect(isSessionId("some title")).toBe(false);
+    expect(isSessionId("42")).toBe(false);
+  });
+});
+
+describe("resolveOpenTarget: latest pending default", () => {
+  test("picks the most recent pending session in scope", () => {
+    // Arrange
+    const sessions = [
+      session({ id: "ses_old", createdAt: "2026-01-01T00:00:00.000Z" }),
+      session({ id: "ses_new", createdAt: "2026-03-01T00:00:00.000Z" }),
+      session({ id: "ses_mid", createdAt: "2026-02-01T00:00:00.000Z" }),
+    ];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan })).toEqual({
+      kind: "session",
+      sessionId: "ses_new",
+    });
+  });
+
+  test("ignores resolved sessions and other artifact types", () => {
+    // Arrange
+    const sessions = [
+      session({ id: "ses_resolved", createdAt: "2026-05-01T00:00:00.000Z", status: "resolved" }),
+      session({ id: "ses_diff", type: "diff", createdAt: "2026-04-01T00:00:00.000Z" }),
+      session({ id: "ses_plan", createdAt: "2026-02-01T00:00:00.000Z" }),
+    ];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan })).toEqual({
+      kind: "session",
+      sessionId: "ses_plan",
+    });
+  });
+
+  test("no pending session in scope reports no-pending", () => {
+    // Arrange
+    const sessions = [session({ id: "ses_done", status: "resolved" })];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan })).toEqual({ kind: "no-pending" });
+  });
+});
+
+describe("resolveOpenTarget: by id", () => {
+  test("an exact session id in scope opens that session, pending or not", () => {
+    // Arrange
+    const sessions = [session({ id: "ses_a" }), session({ id: "ses_b", status: "resolved" })];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "ses_b" })).toEqual({
+      kind: "session",
+      sessionId: "ses_b",
+    });
+  });
+
+  test("an id outside the scope does not match", () => {
+    // Arrange
+    const sessions = [session({ id: "ses_diff", type: "diff" })];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "ses_diff" })).toEqual({
+      kind: "no-match",
+      selector: "ses_diff",
+    });
+  });
+});
+
+describe("resolveOpenTarget: fuzzy by title", () => {
+  test("case-insensitive exact title wins over substring rivals", () => {
+    // Arrange
+    const sessions = [
+      session({ id: "ses_exact", title: "Rollout" }),
+      session({ id: "ses_sub", title: "Rollout plan v2" }),
+    ];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "rollout" })).toEqual({
+      kind: "session",
+      sessionId: "ses_exact",
+    });
+  });
+
+  test("a unique case-insensitive substring match wins", () => {
+    // Arrange
+    const sessions = [
+      session({ id: "ses_auth", title: "Auth rewrite" }),
+      session({ id: "ses_cache", title: "Cache warmup" }),
+    ];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "AUTH" })).toEqual({
+      kind: "session",
+      sessionId: "ses_auth",
+    });
+  });
+
+  test("several substring matches are ambiguous and list the candidate titles", () => {
+    // Arrange
+    const sessions = [
+      session({ id: "ses_1", title: "Payments rollout" }),
+      session({ id: "ses_2", title: "Rollout of search" }),
+    ];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "rollout" })).toEqual({
+      kind: "ambiguous",
+      selector: "rollout",
+      titles: ["Payments rollout", "Rollout of search"],
+    });
+  });
+
+  test("no title match reports no-match", () => {
+    // Arrange
+    const sessions = [session({ id: "ses_1", title: "Auth rewrite" })];
+
+    // Assert
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "billing" })).toEqual({
+      kind: "no-match",
+      selector: "billing",
+    });
+  });
+});
+
+describe("openTargetMessage", () => {
+  test("no-pending mirrors the clean-tree tone", () => {
+    expect(openTargetMessage("plan", { kind: "no-pending" })).toBe(
+      "no pending plan review - nothing to open",
+    );
+  });
+
+  test("no-match names the selector", () => {
+    expect(openTargetMessage("diff", { kind: "no-match", selector: "billing" })).toBe(
+      'no diff review matches "billing" - nothing to open',
+    );
+  });
+
+  test("ambiguous lists the candidate titles", () => {
+    // Act
+    const message = openTargetMessage("plan", {
+      kind: "ambiguous",
+      selector: "rollout",
+      titles: ["A", "B"],
+    });
+
+    // Assert
+    expect(message).toContain('"rollout" matches several plan reviews');
+    expect(message).toContain("  - A");
+    expect(message).toContain("  - B");
+  });
+});