cueloop 0.1.0-alpha.2 → 0.1.0-alpha.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
@@ -10,9 +10,9 @@
     ".": "./src/main.ts"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.2",
-    "@cueloop/daemon": "0.1.0-alpha.2",
-    "@cueloop/client": "0.1.0-alpha.2"
+    "@cueloop/schema": "0.1.0-alpha.21",
+    "@cueloop/daemon": "0.1.0-alpha.21",
+    "@cueloop/client": "0.1.0-alpha.21"
   },
   "publishConfig": {
     "access": "public"
@@ -28,5 +28,10 @@
     "type": "git",
     "url": "git+https://github.com/mmurakaru/cueloop.git",
     "directory": "packages/cli"
-  }
-}
+  },
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
+  },
+  "description": "Terminal review surface for coding agents: annotate plans and diffs, return a verdict, send structured feedback back"
+}

package/src/args.ts

@@ -9,16 +9,16 @@ export function parseArgs(argv: string[]): ParsedArgs {
   const positional: string[] = [];
   const flags: Record<string, string | boolean> = {};
   for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]!;
-    if (!a.startsWith("--")) {
-      positional.push(a);
+    const argument = argv[i]!;
+    if (!argument.startsWith("--")) {
+      positional.push(argument);
       continue;
     }
-    const eq = a.indexOf("=");
-    if (eq !== -1) {
-      flags[a.slice(2, eq)] = a.slice(eq + 1);
+    const equalsIndex = argument.indexOf("=");
+    if (equalsIndex !== -1) {
+      flags[argument.slice(2, equalsIndex)] = argument.slice(equalsIndex + 1);
     } else {
-      const key = a.slice(2);
+      const key = argument.slice(2);
       const next = argv[i + 1];
       if (next !== undefined && !next.startsWith("--")) {
         flags[key] = next;
@@ -31,7 +31,7 @@ export function parseArgs(argv: string[]): ParsedArgs {
   return { positional, flags };
 }
 
-export function flagStr(flags: Record<string, string | boolean>, key: string): string | undefined {
-  const v = flags[key];
-  return typeof v === "string" ? v : undefined;
+export function stringFlag(flags: Record<string, string | boolean>, key: string): string | undefined {
+  const value = flags[key];
+  return typeof value === "string" ? value : undefined;
 }

package/src/main.ts

@@ -1,16 +1,27 @@
 #!/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 verb-first
+ * openers `cueloop plan|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 { resolveWorkspace, workingTreeDiff } from "./workspace";
+import { parseArgs, stringFlag, type ParsedArgs } from "./args";
+import {
+  isDiffReview,
+  isPlanReview,
+  isPrReview,
+  isSessionId,
+  openTargetMessage,
+  resolveOpenTarget,
+} from "./open-target";
+import { sessionCommand } from "./session-commands";
+import { workingTreeDiff } from "./working-tree";
 import { DaemonClient } from "@cueloop/daemon/client";
+import type { ReviewSession } from "@cueloop/schema";
+import { openReview, resolveWorkspace } from "@cueloop/daemon/review";
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
@@ -31,29 +42,17 @@ async function main(): Promise<number> {
       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 session = await client.sessionCreate(workspace, {
-        type: "diff",
-        content: diff,
-        meta: { title: `working tree @ ${workspace.branch}`, cwd: process.cwd() },
-      });
-      client.close();
-      return runTui(session.id);
-    }
+    case "plan":
+      return planCommand(argv.slice(1));
+    case "diff":
+      return diffCommand(argv.slice(1));
     case "serve": {
       const { positional, flags } = parseArgs(argv.slice(1));
-      const port = flagStr(flags, "port");
+      const port = stringFlag(flags, "port");
       const { serveClient } = await import("@cueloop/client");
       const handle = await serveClient({
         port: port !== undefined ? Number(port) : undefined,
-        host: flagStr(flags, "host"),
+        host: stringFlag(flags, "host"),
         sessionId: positional[0],
       });
       console.log(
@@ -73,10 +72,8 @@ async function main(): Promise<number> {
       await new Promise(() => {}); // serve until signalled
       return 0;
     }
-    case "review": {
-      const { reviewCommand } = await import("./pr");
-      return reviewCommand(argv.slice(1));
-    }
+    case "review":
+      return reviewEntry(argv.slice(1));
     case "review-post": {
       const { reviewPostCommand } = await import("./pr");
       return reviewPostCommand(argv.slice(1));
@@ -96,6 +93,103 @@ async function main(): Promise<number> {
   }
 }
 
+/**
+ * The id-or-title selector for a verb-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 verb'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: ReviewSession) => boolean,
+  label: string,
+  selector: string | undefined,
+  emptyMessage?: string,
+): Promise<number> {
+  const client = await DaemonClient.connect({ autostart: true });
+  let sessions: ReviewSession[];
+  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 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.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,
+    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 });
@@ -109,8 +203,12 @@ function printHelp(): void {
       "usage:",
       "  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 diff [id|title]          open the latest pending diff review (or one by id/title);",
+      "                                   with a dirty working tree and no argument, create one instead",
+      "  cueloop review [id|title]        open the latest pending PR review (or one by id/title)",
       "  cueloop review <pr>              review a pull request (--no-tui prints the session)",
+      "  cueloop <plan|diff|review> --latest  open the latest pending review of that type",
       "  cueloop review-post <id> <pr>    post a resolved session's verdict back to the PR",
       "  cueloop serve [session-id]       share over ssh: observers are read-only,",
       "                                   you stay the controller (--port 2222, --host 127.0.0.1;",

package/src/open-target.test.ts

@@ -0,0 +1,185 @@
+/**
+ * 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). No daemon and no TUI - the resolver is pure over the array.
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { ArtifactType, ReviewSession } from "@cueloop/schema";
+import {
+  isDiffReview,
+  isPlanReview,
+  isPrReview,
+  isSessionId,
+  openTargetMessage,
+  resolveOpenTarget,
+} from "./open-target";
+
+function session(overrides: {
+  id: string;
+  type?: ArtifactType;
+  title?: string;
+  status?: "pending" | "resolved";
+  createdAt?: string;
+  pr?: string;
+}): ReviewSession {
+  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("verb 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("a PR review resolves under exactly one scope - never both diff and review", () => {
+    const prReview = session({ id: "ses_pr", type: "diff", pr: "42" });
+    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", () => {
+    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" }),
+    ];
+    expect(resolveOpenTarget(sessions, { match: isPlan })).toEqual({ kind: "session", sessionId: "ses_new" });
+  });
+
+  test("ignores resolved sessions and other artifact types", () => {
+    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" }),
+    ];
+    expect(resolveOpenTarget(sessions, { match: isPlan })).toEqual({ kind: "session", sessionId: "ses_plan" });
+  });
+
+  test("no pending session in scope reports no-pending", () => {
+    const sessions = [session({ id: "ses_done", status: "resolved" })];
+    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", () => {
+    const sessions = [
+      session({ id: "ses_a" }),
+      session({ id: "ses_b", status: "resolved" }),
+    ];
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "ses_b" })).toEqual({
+      kind: "session",
+      sessionId: "ses_b",
+    });
+  });
+
+  test("an id outside the scope does not match", () => {
+    const sessions = [session({ id: "ses_diff", type: "diff" })];
+    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", () => {
+    const sessions = [
+      session({ id: "ses_exact", title: "Rollout" }),
+      session({ id: "ses_sub", title: "Rollout plan v2" }),
+    ];
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "rollout" })).toEqual({
+      kind: "session",
+      sessionId: "ses_exact",
+    });
+  });
+
+  test("a unique case-insensitive substring match wins", () => {
+    const sessions = [
+      session({ id: "ses_auth", title: "Auth rewrite" }),
+      session({ id: "ses_cache", title: "Cache warmup" }),
+    ];
+    expect(resolveOpenTarget(sessions, { match: isPlan, selector: "AUTH" })).toEqual({
+      kind: "session",
+      sessionId: "ses_auth",
+    });
+  });
+
+  test("several substring matches are ambiguous and list the candidate titles", () => {
+    const sessions = [
+      session({ id: "ses_1", title: "Payments rollout" }),
+      session({ id: "ses_2", title: "Rollout of search" }),
+    ];
+    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", () => {
+    const sessions = [session({ id: "ses_1", title: "Auth rewrite" })];
+    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", () => {
+    const message = openTargetMessage("plan", { kind: "ambiguous", selector: "rollout", titles: ["A", "B"] });
+    expect(message).toContain('"rollout" matches several plan reviews');
+    expect(message).toContain("  - A");
+    expect(message).toContain("  - B");
+  });
+});

package/src/open-target.ts

@@ -0,0 +1,106 @@
+/**
+ * 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,14 @@ 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, {
+  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"]) {

package/src/session-commands.ts

@@ -0,0 +1,116 @@
+/**
+ * `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 { 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];
+  const client = await DaemonClient.connect({ autostart: true });
+  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: a review created from inside herdr spawns a new tab
+        // that renders it. Guarded to genuinely new sessions and no-op outside
+        // herdr; a broken binary never blocks the create.
+        openHerdrPaneForReview(review.session);
+        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 body = stringFlag(flags, "body") ?? "";
+        const quote = required(stringFlag(flags, "quote"), "--quote");
+        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,
+          }),
+        );
+        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();
+        out(await client.sessionSubmitRevision(id, content));
+        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;
+}

package/src/{workspace.ts → working-tree.ts}

@@ -1,6 +1,4 @@
-/** Workspace key resolution (#9): repo root + branch from the cwd. */
-
-import type { WorkspaceKey } from "@cueloop/schema";
+/** Working-tree diff capture for `cueloop diff`, untracked files included. */
 
 async function git(args: string[], cwd: string): Promise<string | null> {
   const proc = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "ignore" });
@@ -9,15 +7,9 @@ async function git(args: string[], cwd: string): Promise<string | null> {
   return out.trim();
 }
 
-export async function resolveWorkspace(cwd = process.cwd()): Promise<WorkspaceKey> {
-  const repoRoot = (await git(["rev-parse", "--show-toplevel"], cwd)) ?? cwd;
-  const branch = (await git(["rev-parse", "--abbrev-ref", "HEAD"], cwd)) ?? "detached";
-  return { repoRoot, branch };
-}
-
 export async function workingTreeDiff(cwd = process.cwd()): Promise<string> {
   const tracked = (await git(["diff", "HEAD"], cwd)) ?? "";
-  // untracked files included by default (map note: changed-first)
+  // untracked files included by default
   const untrackedList = (await git(["ls-files", "--others", "--exclude-standard"], cwd)) ?? "";
   let untracked = "";
   for (const file of untrackedList.split("\n").filter(Boolean)) {

package/src/session-cmds.ts

@@ -1,114 +0,0 @@
-/**
- * `cueloop session *` - mirrors the daemon socket API 1:1 (#14). 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 type { ArtifactType, VerdictKind } from "@cueloop/schema";
-import { DaemonClient } from "@cueloop/daemon/client";
-import { parseArgs, flagStr } from "./args";
-import { resolveWorkspace } from "./workspace";
-
-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];
-  const client = await DaemonClient.connect({ autostart: true });
-  try {
-    switch (verb) {
-      case "create": {
-        const workspace = await resolveWorkspace(flagStr(flags, "cwd"));
-        const contentFile = flagStr(flags, "content-file");
-        const content = contentFile ? await Bun.file(contentFile).text() : await readStdin();
-        const session = await client.sessionCreate(workspace, {
-          type: (flagStr(flags, "type") ?? "plan") as ArtifactType,
-          content,
-          meta: {
-            agent: flagStr(flags, "agent"),
-            agentSessionId: flagStr(flags, "agent-session-id"),
-            planPath: flagStr(flags, "plan-path"),
-            title: flagStr(flags, "title"),
-            cwd: flagStr(flags, "cwd") ?? process.cwd(),
-          },
-        });
-        out(session);
-        return 0;
-      }
-      case "get": {
-        out(await client.sessionGet(required(positional[1], "session id")));
-        return 0;
-      }
-      case "list": {
-        const status = flagStr(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(flagStr(flags, "timeout-ms") ?? "60000");
-        const session = await client.sessionWait(id, timeoutMs);
-        if (session === null) {
-          out({ status: "pending" });
-          return 0;
-        }
-        out({
-          status: "resolved",
-          allow: session.verdict!.kind === "approve",
-          verdict: session.verdict!.kind,
-          feedback: session.verdict!.feedback,
-        });
-        return 0;
-      }
-      case "annotate": {
-        const id = required(positional[1], "session id");
-        const body = flagStr(flags, "body") ?? "";
-        const quote = required(flagStr(flags, "quote"), "--quote");
-        out(
-          await client.sessionAnnotate(id, {
-            id: flagStr(flags, "annotation-id") ?? `a_${Date.now().toString(36)}`,
-            kind: flagStr(flags, "kind") ?? "comment",
-            anchor: {
-              quote,
-              prefix: flagStr(flags, "prefix") ?? "",
-              suffix: flagStr(flags, "suffix") ?? "",
-            },
-            body,
-          }),
-        );
-        return 0;
-      }
-      case "resolve": {
-        const id = required(positional[1], "session id");
-        const kind = required(flagStr(flags, "verdict"), "--verdict") as VerdictKind;
-        out(await client.sessionResolve(id, kind, flagStr(flags, "summary") ?? ""));
-        return 0;
-      }
-      case "submit-revision": {
-        const id = required(positional[1], "session id");
-        const contentFile = flagStr(flags, "content-file");
-        const content = contentFile ? await Bun.file(contentFile).text() : await readStdin();
-        out(await client.sessionSubmitRevision(id, content));
-        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>(v: T | undefined, what: string): T {
-  if (v === undefined) throw new Error(`missing ${what}`);
-  return v;
-}