cueloop 0.1.0-alpha.72 → 0.1.0-alpha.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.72",
+  "version": "0.1.0-alpha.74",
   "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.72",
-    "@cueloop/client": "0.1.0-alpha.72",
-    "@cueloop/daemon": "0.1.0-alpha.72",
-    "@cueloop/schema": "0.1.0-alpha.72",
+    "@cueloop/adapters": "0.1.0-alpha.74",
+    "@cueloop/client": "0.1.0-alpha.74",
+    "@cueloop/daemon": "0.1.0-alpha.74",
+    "@cueloop/schema": "0.1.0-alpha.74",
     "valibot": "^1.4.2"
   },
   "engines": {

package/src/daemon-control.test.ts

@@ -0,0 +1,43 @@
+/**
+ * `cueloop stop`'s primitive against a real detached daemon: stopping it clears
+ * the socket and pid so the next launch autostarts a fresh one (the self-heal
+ * `cueloop update` relies on), and stopping when none runs is a no-op.
+ */
+
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { pidPath, socketPath } from "@cueloop/daemon/paths";
+import { stopDaemon } from "./daemon-control";
+
+let home: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-stop-"));
+});
+afterEach(async () => {
+  await stopDaemon(home).catch(() => undefined);
+  rmSync(home, { recursive: true, force: true });
+});
+
+test("stopDaemon stops a running daemon and clears its socket and pid", async () => {
+  // Arrange - a real detached daemon owns the home
+  const client = await DaemonClient.connect({ home, autostart: true });
+
+  client.close();
+  expect(existsSync(socketPath(home))).toBe(true);
+
+  // Act
+  const stopped = await stopDaemon(home);
+
+  // Assert - it reported a stop, and the daemon released its socket and pid
+  expect(stopped).toBe(true);
+  expect(existsSync(socketPath(home))).toBe(false);
+  expect(existsSync(pidPath(home))).toBe(false);
+}, 60_000);
+
+test("stopDaemon reports nothing to stop when no daemon is running", async () => {
+  expect(await stopDaemon(home)).toBe(false);
+});

package/src/daemon-control.ts

@@ -0,0 +1,108 @@
+/**
+ * Local daemon control: `cueloop stop` and `cueloop restart`, and the
+ * `stopDaemon` primitive `cueloop update` calls so a newer binary is not left
+ * talking to the old-version daemon (which refuses the handshake).
+ */
+
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import * as v from "valibot";
+import { DaemonClient } from "@cueloop/daemon/client";
+import { cueloopHome, pidPath, socketPath } from "@cueloop/daemon/paths";
+
+const ProcessIdSchema = v.pipe(
+  v.string(),
+  v.transform((raw) => Number(raw.trim())),
+  v.integer(),
+  v.minValue(1),
+);
+
+/** Signal the daemon through its pid file; callers only reach this while a socket proves it is live. */
+function signalDaemonByProcessId(home: string): boolean {
+  const path = pidPath(home);
+
+  if (!existsSync(path)) return false;
+  let raw: string;
+
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return false;
+  }
+  const parsed = v.safeParse(ProcessIdSchema, raw);
+
+  if (!parsed.success) return false;
+  try {
+    process.kill(parsed.output);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True once the stopped daemon has released its socket; false if it is still there at the deadline. */
+async function waitForSocketGone(home: string): Promise<boolean> {
+  const path = socketPath(home);
+  const deadline = Date.now() + 5_000;
+
+  while (Date.now() < deadline) {
+    if (!existsSync(path)) return true;
+    await Bun.sleep(50);
+  }
+
+  return !existsSync(path);
+}
+
+/**
+ * Stop the daemon that owns `home`, returning true once its socket is released.
+ * A live daemon is stopped by the owner-gated shutdown request, or, when it
+ * refuses the handshake (a version mismatch), by signalling its pid - safe
+ * because the socket proves the pid file is current. A home with no socket has
+ * no live daemon to stop, so its pid file is never trusted.
+ */
+export async function stopDaemon(home = cueloopHome()): Promise<boolean> {
+  if (!existsSync(socketPath(home))) return false;
+  try {
+    const client = await DaemonClient.connect({ home, autostart: false });
+
+    await client.shutdown();
+    client.close();
+  } catch {
+    if (!signalDaemonByProcessId(home)) return false;
+  }
+
+  return waitForSocketGone(home);
+}
+
+/** `cueloop stop` - stop the local daemon. */
+export async function stopCommand(): Promise<number> {
+  const home = cueloopHome();
+
+  if (!existsSync(socketPath(home))) {
+    console.log("no cueloop daemon is running");
+
+    return 0;
+  }
+  const stopped = await stopDaemon(home);
+
+  console.log(stopped ? "cueloop daemon stopped" : "cueloop daemon did not stop in time");
+
+  return stopped ? 0 : 1;
+}
+
+/** `cueloop restart` - stop the local daemon, then autostart a fresh one. */
+export async function restartCommand(): Promise<number> {
+  const home = cueloopHome();
+
+  await stopDaemon(home);
+  // a wedged daemon that never released its socket would otherwise be reused, not replaced
+  const socket = socketPath(home);
+
+  if (existsSync(socket)) rmSync(socket, { force: true });
+  const client = await DaemonClient.connect({ home, autostart: true });
+
+  client.close();
+  console.log("cueloop daemon restarted");
+
+  return 0;
+}

package/src/main.ts

@@ -23,9 +23,8 @@ import {
 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";
+import { openReview } from "@cueloop/daemon/review";
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
@@ -105,6 +104,8 @@ interface CommandHandlers {
 const commandHandlers: CommandHandlers = {
   session: (rest) => sessionCommand(rest),
   daemon: (rest) => daemonCommand(rest),
+  stop: async () => (await import("./daemon-control")).stopCommand(),
+  restart: async () => (await import("./daemon-control")).restartCommand(),
   plan: (rest) => planCommand(rest),
   reply: (rest) => replyCommand(rest),
   diff: (rest) => diffCommand(rest),
@@ -165,6 +166,7 @@ async function openReviewOfKind(
   match: (session: Thread) => boolean,
   label: string,
   selector: string | undefined,
+  layout: "review" | "plan" | undefined,
   emptyMessage?: string,
 ): Promise<number> {
   const client = await DaemonClient.connect({ autostart: true });
@@ -177,7 +179,7 @@ async function openReviewOfKind(
   }
   const target = resolveOpenTarget(sessions, { match, selector });
 
-  if (target.kind === "session") return runTui(target.sessionId);
+  if (target.kind === "session") return runTui(target.sessionId, layout);
   if (target.kind === "no-pending" && emptyMessage !== undefined) {
     console.error(emptyMessage);
 
@@ -190,7 +192,7 @@ async function openReviewOfKind(
 
 /** `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)));
+  return openReviewOfKind(isPlanReview, "plan", openSelector(parseArgs(argv)), "plan");
 }
 
 /**
@@ -199,7 +201,7 @@ async function planCommand(argv: string[]): Promise<number> {
  * 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)));
+  return openReviewOfKind(isReplyReview, "reply", openSelector(parseArgs(argv)), "plan");
 }
 
 /**
@@ -219,7 +221,7 @@ async function prototypeCommand(argv: string[]): Promise<number> {
     selector !== undefined && !isSessionId(selector) && (isHtmlPrototype || isMarkdownPrototype);
 
   if (wantsOpen || !looksLikeFile)
-    return openReviewOfKind(isPrototypeReview, "prototype", selector);
+    return openReviewOfKind(isPrototypeReview, "prototype", selector, "plan");
 
   const path = resolve(selector);
   const content = await Bun.file(path)
@@ -242,47 +244,30 @@ async function prototypeCommand(argv: string[]): Promise<number> {
 
   client.close();
 
-  return runTui(review.id);
+  return runTui(review.id, "plan");
 }
 
 /**
- * `cueloop diff` disambiguates create from open by intent:
+ * `cueloop diff` opens the repo's workbench in the review layout:
  *   - 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.
+ *     opens a specific pending diff thread;
+ *   - a bare `cueloop diff` find-or-creates the per-repo workbench thread - a live-diff
+ *     annotation container - so it is immediately annotatable and always shows the
+ *     current working tree, reusing the same thread across re-runs.
  */
 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);
+  if (wantsOpen) return openReviewOfKind(isDiffReview, "diff", selector, "review");
 
-  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}`,
-  });
+  const workbench = await client.sessionWorkbench(process.cwd());
 
   client.close();
 
-  return runTui(review.id);
+  return runTui(workbench.id, "review");
 }
 
 /**
@@ -308,13 +293,21 @@ async function reviewEntry(argv: string[]): Promise<number> {
     isPrReview,
     "PR",
     explicitOpen || looksLikeSessionId ? selector : undefined,
+    "review",
   );
 }
 
-async function runTui(sessionId?: string): Promise<number> {
-  const { runClient } = await import("@cueloop/client");
+/**
+ * A create-command dictates the pane composition it opens in; a bare launch (`layout`
+ * omitted) restores the remembered one. Resolve the factory here so the heavy client
+ * module stays lazily imported for non-TUI commands.
+ */
+async function runTui(sessionId?: string, layout?: "review" | "plan"): Promise<number> {
+  const { runClient, reviewLayout, planLayout } = await import("@cueloop/client");
+  const resolved =
+    layout === "review" ? reviewLayout() : layout === "plan" ? planLayout() : undefined;
 
-  return runClient({ sessionId });
+  return runClient({ sessionId, layout: resolved });
 }
 
 function printHelp(): void {
@@ -354,6 +347,8 @@ function printHelp(): void {
       "  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 stop                     stop the local daemon",
+      "  cueloop restart                  stop the local daemon and start a fresh one",
       "  cueloop dev                      open the TUI on an isolated home seeded with example threads",
       "",
       "  cueloop -v, --version            print the installed version",

package/src/pr.ts

@@ -80,9 +80,9 @@ export async function reviewCommand(argv: string[]): Promise<number> {
     return 0;
   }
 
-  const { runClient } = await import("@cueloop/client");
+  const { runClient, reviewLayout } = await import("@cueloop/client");
 
-  await runClient({ sessionId: session.id });
+  await runClient({ sessionId: session.id, layout: reviewLayout() });
 
   const after = await getSession(session.id);
 

package/src/share-command.test.ts

@@ -133,6 +133,43 @@ describe(shareSession, () => {
     expect(deps.lines).toEqual(["share link copied - ssh p_abc123xy@cueloop.dev"]);
   });
 
+  test("freezes a workbench thread's live diff into the shared artifact", async () => {
+    // Arrange - a workbench thread (renders live locally) plus a daemon that reports a fresh diff
+    const workbench = sessionFixture("ses_wb", {
+      artifact: {
+        type: "diff",
+        content: "STALE",
+        files: [],
+        meta: { workbench: true, title: "Workbench" },
+      },
+    });
+    const client = {
+      ...fakeClient([workbench]),
+      repoDiff: async () => ({
+        patch: "FRESH",
+        files: [{ path: "x.ts", oldContents: "", newContents: "y\n", status: "added" as const }],
+      }),
+    };
+    let published: Thread | undefined;
+    const deps = depsSpy({
+      publish: mock(async (session: Thread) => {
+        published = session;
+
+        return { line: "ssh p_abc123xy@cueloop.dev", copied: true };
+      }),
+    });
+
+    // Act
+    const code = await shareSession(client, { sessionId: "ses_wb" }, deps);
+
+    // Assert - the remote gets the fresh snapshot, marked so it renders frozen while keeping its notes
+    expect(code).toBe(0);
+    expect(published?.artifact.content).toBe("FRESH");
+    expect(published?.artifact.files).toHaveLength(1);
+    expect(published?.artifact.meta.snapshot).toBe(true);
+    expect(published?.artifact.meta.workbench).toBe(true);
+  });
+
   test("without an id, shares the most recent session", async () => {
     // Arrange
     const publish = mock(

package/src/share-command.ts

@@ -12,6 +12,7 @@ import {
   publishShare,
   pullShare,
   shareIdFromLine,
+  snapshotWorkbench,
   type ShareResult,
   type ShareTarget,
 } from "@cueloop/client";
@@ -81,7 +82,11 @@ export async function shareSession(
     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 });
+  // a workbench thread renders live locally; freeze its diff so the remote reviewer gets a stable snapshot
+  const shared = client.repoDiff
+    ? await snapshotWorkbench(session, client.repoDiff.bind(client))
+    : session;
+  const { line, copied } = await deps.publish(shared, { host: params.host, port: params.port });
   const shareId = shareIdFromLine(line);
 
   if (shareId) await client.sessionSetShareId(session.id, shareId);

package/src/update-command.test.ts

@@ -3,16 +3,22 @@
 import { describe, expect, mock, test } from "bun:test";
 import { resolveInstallDir, runUpdate, type UpdateDeps } from "./update-command";
 
-function depsSpy(overrides: Partial<UpdateDeps> = {}): UpdateDeps & { lines: string[] } {
+function depsSpy(
+  overrides: Partial<UpdateDeps> = {},
+): UpdateDeps & { lines: string[]; errorLines: string[] } {
   const lines: string[] = [];
+  const errorLines: string[] = [];
 
   return {
     currentVersion: "0.1.0-alpha.68",
     installDir: () => "/Users/dev/.local/bin",
     fetchLatestVersion: mock(async () => "0.1.0-alpha.68"),
     runInstaller: mock(async () => 0),
+    stopDaemon: mock(async () => true),
     out: (message: string) => void lines.push(message),
+    error: (message: string) => void errorLines.push(message),
     lines,
+    errorLines,
     ...overrides,
   };
 }
@@ -116,9 +122,27 @@ describe(runUpdate, () => {
     // Act
     const code = await runUpdate(deps, false);
 
-    // Assert
+    // Assert - it also stops the stale-version daemon so the next launch autostarts the new build
     expect(code).toBe(0);
     expect(deps.runInstaller).toHaveBeenCalledWith("/Users/dev/.local/bin");
+    expect(deps.stopDaemon).toHaveBeenCalledTimes(1);
+    expect(deps.lines).toContain("Update ran successfully! Please restart cueloop.");
+  });
+
+  test("a failing daemon stop never fails an install that already succeeded", async () => {
+    // Arrange - the install succeeds but the cleanup stop rejects
+    const deps = depsSpy({
+      fetchLatestVersion: mock(async () => "0.1.0-alpha.99"),
+      stopDaemon: mock(async () => {
+        throw new Error("pid file vanished");
+      }),
+    });
+
+    // Act
+    const code = await runUpdate(deps, false);
+
+    // Assert - the update still reports success
+    expect(code).toBe(0);
     expect(deps.lines).toContain("Update ran successfully! Please restart cueloop.");
   });
 
@@ -143,8 +167,9 @@ describe(runUpdate, () => {
     // Act
     const code = await runUpdate(deps, false);
 
-    // Assert
+    // Assert - a failed install leaves the current daemon alone
     expect(code).toBe(1);
+    expect(deps.stopDaemon).not.toHaveBeenCalled();
     expect(deps.lines).not.toContain("Update ran successfully! Please restart cueloop.");
   });
 
@@ -155,9 +180,24 @@ describe(runUpdate, () => {
     // Act
     const code = await runUpdate(deps, false);
 
+    // Assert - the failure goes to stderr, and no progress prints to stdout
+    expect(code).toBe(1);
+    expect(deps.errorLines[0]).toContain("must be an absolute path");
+    expect(deps.lines).toHaveLength(0);
+    expect(deps.runInstaller).not.toHaveBeenCalled();
+  });
+
+  test("reports an unresolvable install dir on stderr with no stdout progress", async () => {
+    // Arrange - neither an override, the binary path, nor HOME resolves a target
+    const deps = depsSpy({ installDir: () => undefined });
+
+    // Act
+    const code = await runUpdate(deps, false);
+
     // Assert
     expect(code).toBe(1);
-    expect(deps.lines[0]).toContain("must be an absolute path");
+    expect(deps.errorLines[0]).toContain("HOME is not set");
+    expect(deps.lines).toHaveLength(0);
     expect(deps.runInstaller).not.toHaveBeenCalled();
   });
 });

package/src/update-command.ts

@@ -1,6 +1,7 @@
 import { basename, dirname, isAbsolute, resolve } from "node:path";
 import * as v from "valibot";
 import { CLI_VERSION } from "./version";
+import { stopDaemon } from "./daemon-control";
 
 const INSTALL_URL = "https://cueloop.dev/install.sh";
 const RELEASES_URL = "https://api.github.com/repos/mmurakaru/cueloop/releases?per_page=100";
@@ -117,7 +118,12 @@ export interface UpdateDeps {
   installDir: () => string | undefined;
   fetchLatestVersion: () => Promise<string | undefined>;
   runInstaller: (targetInstallDir: string) => Promise<number>;
+  /** Stop the running daemon after an update so the next launch autostarts the new build; resolves true when one was stopped. */
+  stopDaemon: () => Promise<boolean>;
+  /** Progress and status, on stdout - not an error, so it must not read as one. */
   out: (message: string) => void;
+  /** A failure that ends the run, on stderr. */
+  error: (message: string) => void;
 }
 
 /**
@@ -130,12 +136,12 @@ export async function runUpdate(deps: UpdateDeps, dryRun: boolean): Promise<numb
   const targetInstallDir = deps.installDir();
 
   if (targetInstallDir === undefined) {
-    deps.out("cueloop update: HOME is not set and the current binary path is unknown");
+    deps.error("cueloop update: HOME is not set and the current binary path is unknown");
 
     return 1;
   }
   if (!targetInstallDir.startsWith("/")) {
-    deps.out("cueloop update: CUELOOP_INSTALL_DIR must be an absolute path");
+    deps.error("cueloop update: CUELOOP_INSTALL_DIR must be an absolute path");
 
     return 1;
   }
@@ -157,7 +163,14 @@ export async function runUpdate(deps: UpdateDeps, dryRun: boolean): Promise<numb
   deps.out(`updating cueloop in ${targetInstallDir}...`);
   const exitCode = await deps.runInstaller(targetInstallDir);
 
-  if (exitCode === 0) deps.out("Update ran successfully! Please restart cueloop.");
+  if (exitCode === 0) {
+    try {
+      await deps.stopDaemon();
+    } catch {
+      // stopping the old daemon is cleanup; it must never fail an install that already succeeded
+    }
+    deps.out("Update ran successfully! Please restart cueloop.");
+  }
 
   return exitCode;
 }
@@ -170,7 +183,9 @@ export async function updateCommand(argv: string[] = []): Promise<number> {
       installDir: () => resolveInstallDir(process.execPath, process.env),
       fetchLatestVersion,
       runInstaller,
-      out: (message) => console.error(message),
+      stopDaemon: () => stopDaemon(),
+      out: (message) => console.log(message),
+      error: (message) => console.error(message),
     },
     argv.includes("--dry-run"),
   );