@cueloop/daemon 0.1.0-alpha.68 → 0.1.0-alpha.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.68",
+  "version": "0.1.0-alpha.69",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -35,8 +35,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.68",
+    "@cueloop/schema": "0.1.0-alpha.69",
     "@pierre/diffs": "^1.3.6",
+    "effect": "^4.0.0-rc.115",
     "valibot": "^1.4.2"
   },
   "engines": {

package/src/api.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { DaemonCore, verdictResponse } from "./api";
@@ -64,6 +64,23 @@ describe("session lifecycle", () => {
     expect(core.sessionGet(session.id).annotations.length).toBe(0);
   });
 
+  test("a welcome-playground note is ephemeral: never persisted", () => {
+    // Arrange
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    // Act
+    core.sessionAnnotate(session.id, {
+      id: "w1",
+      kind: "comment",
+      anchor: { quote: "start", prefix: "", suffix: "" },
+      target: { kind: "welcome" },
+      body: "just trying it",
+    });
+
+    // Assert - the onboarding playground stores nothing
+    expect(core.sessionGet(session.id).annotations.length).toBe(0);
+  });
+
   test("annotate with an author registers them in the participant registry", () => {
     // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
@@ -896,3 +913,85 @@ describe("tree primitives", () => {
     expect(rerouted.annotations[0]!.resolution).toBeUndefined();
   });
 });
+
+describe("workbench session", () => {
+  function makeRepo(): string {
+    const root = mkdtempSync(join(tmpdir(), "cueloop-wb-repo-"));
+
+    // a unique seed file so each repo's root commit is a distinct SHA (empty commits in the same
+    // second hash identically) - the root commit is the per-project key under test
+    writeFileSync(join(root, "seed.txt"), root);
+    Bun.spawnSync(["git", "-C", root, "init", "-q"]);
+    Bun.spawnSync(["git", "-C", root, "config", "user.email", "t@e.st"]);
+    Bun.spawnSync(["git", "-C", root, "config", "user.name", "T"]);
+    Bun.spawnSync(["git", "-C", root, "add", "-A"]);
+    Bun.spawnSync(["git", "-C", root, "commit", "-q", "-m", "seed"]);
+
+    return root;
+  }
+
+  test("creates a diff-backed, workbench-marked thread and attaches idempotently", async () => {
+    const repo = makeRepo();
+
+    try {
+      const first = await core.workbenchSession(repo);
+
+      expect(first.artifact.meta.workbench).toBe(true);
+      expect(first.artifact.type).toBe("diff");
+      expect(first.workspace.rootCommit).toBeTruthy();
+
+      // a second call for the same repo returns the same thread, never a duplicate
+      const second = await core.workbenchSession(repo);
+
+      expect(second.id).toBe(first.id);
+      expect(core.sessionList().filter((s) => s.artifact.meta.workbench).length).toBe(1);
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+    }
+  });
+
+  test("a resolved workbench is not reused; a fresh one is created past it", async () => {
+    const repo = makeRepo();
+
+    try {
+      const first = await core.workbenchSession(repo);
+
+      core.sessionResolve(first.id, "comment", "");
+      const second = await core.workbenchSession(repo);
+
+      expect(second.id).not.toBe(first.id);
+      expect(second.status).toBe("pending");
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+    }
+  });
+
+  test("concurrent bare launches for one repo share a single workbench", async () => {
+    const repo = makeRepo();
+
+    try {
+      const [a, b] = await Promise.all([core.workbenchSession(repo), core.workbenchSession(repo)]);
+
+      expect(a.id).toBe(b.id);
+      expect(core.sessionList().filter((s) => s.artifact.meta.workbench).length).toBe(1);
+    } finally {
+      rmSync(repo, { recursive: true, force: true });
+    }
+  });
+
+  test("keys the workbench by root commit: different repos get different threads", async () => {
+    const repoA = makeRepo();
+    const repoB = makeRepo();
+
+    try {
+      const a = await core.workbenchSession(repoA);
+      const b = await core.workbenchSession(repoB);
+
+      expect(a.id).not.toBe(b.id);
+      expect(a.workspace.rootCommit).not.toBe(b.workspace.rootCommit);
+    } finally {
+      rmSync(repoA, { recursive: true, force: true });
+      rmSync(repoB, { recursive: true, force: true });
+    }
+  });
+});

package/src/api.ts

@@ -21,6 +21,7 @@ import {
   viewOfPath,
   isAddressed,
   isAgentNote,
+  annotationTarget,
   isMarkdownArtifact,
   MAIN_BRANCH,
   parseBlocks,
@@ -47,7 +48,7 @@ import { SessionStore, withHistory } from "./store";
 import { pruneExpiredSessions, resolveCleanupPeriodDays } from "./retention";
 import { HerdrTabStore, type HerdrTabHandle } from "./herdr-tab-store";
 import { DiffWatcher } from "./diff-watcher";
-import { workingTreeDiff, workingChangeList } from "./working-tree";
+import { workingTreeDiff, workingChangeList, type WorkingTreeDiff } from "./working-tree";
 import { listProjectFiles, readProjectFile } from "./project-files";
 import { resolveWorkspace } from "./review";
 import { DaemonError } from "./errors";
@@ -90,6 +91,8 @@ export class DaemonCore {
    * result, so overlapping captures never write an older patch over a newer one.
    */
   private readonly diffRefreshGenerations = new Map<string, number>();
+  /** In-flight workbench creations keyed by project, so concurrent bare launches share one thread. */
+  private readonly workbenchCreation = new Map<string, Promise<ReviewSession>>();
 
   constructor(home: string) {
     this.store = new SessionStore(home);
@@ -226,6 +229,8 @@ export class DaemonCore {
     authorName?: string,
   ): ReviewSession {
     const session = this.mutable(id);
+    // a welcome-playground note is ephemeral by design: never persisted, so never fed back
+    if (annotationTarget(annotation).kind === "welcome") return session;
     const existing = session.annotations.findIndex((candidate) => candidate.id === annotation.id);
     const full: Annotation = { ...annotation, createdAt: new Date().toISOString() };
 
@@ -363,6 +368,60 @@ export class DaemonCore {
     return workingChangeList(cwd);
   }
 
+  /**
+   * The live working-tree diff (HEAD vs working tree, untracked included) at `cwd`:
+   * the same unified patch plus full per-file contents a `cueloop diff` captures,
+   * so the Changes navigator renders a real diff for any thread. Owner-only.
+   */
+  repoDiff(cwd: string): Promise<WorkingTreeDiff> {
+    return workingTreeDiff(cwd);
+  }
+
+  /**
+   * The per-repo workbench thread for `cwd`: a self-initiated review of the current checkout, keyed by
+   * the repo's root-commit identity (a standalone bucket when there is none). Returns the existing one
+   * or lazily creates it with the working-tree diff as its artifact, so a bare launch persists its
+   * first comment without an agent submission. Owner-only.
+   */
+  async workbenchSession(cwd: string): Promise<ReviewSession> {
+    const workspace = await resolveWorkspace(cwd);
+    const key = workspace.rootCommit ?? "_standalone";
+    // an open workbench is reused; a resolved one is immutable and would reject the note, so a fresh
+    // one is created past it
+    const open = this.store
+      .list()
+      .find(
+        (session) =>
+          session.artifact.meta.workbench === true &&
+          session.status !== "resolved" &&
+          (session.workspace.rootCommit ?? "_standalone") === key,
+      );
+
+    if (open) return open;
+    // serialize concurrent bare launches for the same repo onto one creation, so they share a thread
+    const inFlight = this.workbenchCreation.get(key);
+
+    if (inFlight) return inFlight;
+    const creation = workingTreeDiff(cwd).then((diff) =>
+      this.sessionCreate({
+        workspace,
+        artifact: {
+          type: "diff",
+          content: diff.patch,
+          files: diff.files,
+          meta: { workbench: true, title: "Workbench", cwd },
+        },
+      }),
+    );
+
+    this.workbenchCreation.set(key, creation);
+    try {
+      return await creation;
+    } finally {
+      this.workbenchCreation.delete(key);
+    }
+  }
+
   sessionSetShareId(id: string, shareId: string): ReviewSession {
     const session = this.mutable(id);
 
@@ -519,12 +578,17 @@ export class DaemonCore {
     return session;
   }
 
-  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): ReviewSession {
+  sessionResolve(
+    id: string,
+    verdictKind: VerdictKind,
+    summary: string,
+    actionBodies?: Record<string, string>,
+  ): ReviewSession {
     const session = this.mutable(id);
     const verdict: Verdict = {
       kind: verdictKind,
       summary,
-      feedback: feedbackForSession(session, verdictKind, summary),
+      feedback: feedbackForSession(session, verdictKind, summary, actionBodies),
       resolvedAt: new Date().toISOString(),
     };
 
@@ -601,6 +665,10 @@ export class DaemonCore {
         annotation.resolution = { revision: revisionNumber, source: "agent" };
       } else if (
         revisedBlocks !== null &&
+        // only a note on the artifact drifts against the artifact's revision; a selector-anchored
+        // pixel element or a file-targeted Changes-diff note anchors elsewhere
+        annotationTarget(annotation).kind === "artifact" &&
+        !annotation.anchor.selector &&
         resolveAnchor(annotation.anchor, revisedBlocks) === null
       ) {
         annotation.resolution = { revision: revisionNumber, source: "drift" };

package/src/capabilities.ts

@@ -43,6 +43,8 @@ const PRIMITIVE_ROLES = {
   "repo.files": "owner",
   "repo.fileContents": "owner",
   "repo.changes": "owner",
+  "repo.diff": "owner",
+  "session.workbench": "owner",
   // the tree is the owner's: collaborators comment on the branch a share follows
   "session.navigate": "owner",
   "session.branch": "owner",

package/src/client.ts

@@ -29,7 +29,9 @@ import type { SharedMerge } from "./api";
 
 export type { SharedMerge } from "./api";
 import { cueloopHome, ownerTokenPath, socketPath } from "./paths";
-import { Params, SessionRecordSchema } from "./validate";
+import { Params, SessionRecordSchema, DiffFileContentsSchema } from "./validate";
+import type { WorkingTreeDiff } from "./working-tree";
+import { DAEMON_VERSION } from "./version";
 
 export type { EventFrame } from "./protocol";
 
@@ -49,7 +51,9 @@ type PendingRequest = {
 };
 
 const EmptyResultSchema = v.object({});
-const PingResultSchema = v.object({ pid: v.number() });
+// version is optional: a daemon from before the handshake carried one reads as
+// undefined, which never equals this build - so it is treated as stale and replaced
+const PingResultSchema = v.object({ pid: v.number(), version: v.optional(v.string()) });
 const RefreshDiffResultSchema = v.object({ changed: v.boolean() });
 const HerdrTabResultSchema = v.nullable(v.object({ tabId: v.string(), paneId: v.string() }));
 
@@ -91,6 +95,10 @@ export interface SessionClient {
   repoFileContents?(cwd: string, path: string): Promise<string | null>;
   /** Changed files (path plus git status) in the working tree at `cwd`. */
   repoChanges?(cwd: string): Promise<{ path: string; status: DiffFileStatus }[]>;
+  /** The live working-tree diff (patch plus per-file contents) at `cwd`. */
+  repoDiff?(cwd: string): Promise<WorkingTreeDiff>;
+  /** Find-or-create the per-repo workbench thread for `cwd`, so a bare launch's first comment persists. */
+  sessionWorkbench?(cwd: string): Promise<ReviewSession>;
   /** Move a branch's tip (the current one, or `branch` after switching to it) back to an entry on its path; a summary records the abandoned segment. */
   sessionNavigate(
     id: string,
@@ -110,7 +118,12 @@ export interface SessionClient {
   sessionDelete(id: string): Promise<void>;
   /** Record the caller's own identity name (collaborator self-naming on a share). */
   sessionSetSelfName(id: string, name: string): Promise<ReviewSession>;
-  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession>;
+  sessionResolve(
+    id: string,
+    verdictKind: VerdictKind,
+    summary: string,
+    actionBodies?: Record<string, string>,
+  ): Promise<ReviewSession>;
   close(): void;
 }
 
@@ -145,6 +158,9 @@ export class DaemonClient implements SessionClient {
   private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
   private writer: BackpressureWriter | null = null;
   private pending = new Map<number, PendingRequest>();
+  /** The connected daemon's build version and pid, learned from the ping handshake. */
+  private daemonVersion: string | undefined;
+  private daemonPid: number | undefined;
   private nextId = 1;
   private eventListeners = new Set<(event: EventFrame) => void>();
   private closed = false;
@@ -162,14 +178,66 @@ export class DaemonClient implements SessionClient {
     client.home = home;
     try {
       await client.dial(path);
-
-      return client;
+      // A daemon from an earlier build lingers after an upgrade; talking to it
+      // means new client, old behaviour. The owner replaces it so an upgrade
+      // never needs a manual restart; without autostart there is nothing to
+      // replace it with, so the caller hears exactly why.
+      if (client.daemonVersion === DAEMON_VERSION) return client;
+      if (!options.autostart) {
+        client.close();
+        throw new DaemonClientError(
+          "version_mismatch",
+          `daemon is version ${client.daemonVersion ?? "unknown"}, but this client is ${DAEMON_VERSION}; restart the daemon`,
+        );
+      }
+      await client.stopStaleDaemon(path);
     } catch (err) {
       // a live daemon that refused the handshake is not a dead socket: the
       // caller hears why instead of the client replacing a running daemon
       if (!options.autostart || err instanceof DaemonClientError) throw err;
     }
-    // Socket dead or absent: clean a stale file and spawn the daemon detached.
+    // Socket dead, absent, or just-replaced: clean a stale file and spawn detached.
+    return client.attachFreshDaemon(home, path);
+  }
+
+  /**
+   * Tear down a daemon from an earlier build so a fresh one can bind: ask it to
+   * shut down (owner-gated) or, failing that, signal its pid, then wait for it to
+   * release the socket. Best-effort - attachFreshDaemon's stale-socket and
+   * stale-lock cleanup recovers even a daemon that never ran its own teardown.
+   */
+  private async stopStaleDaemon(path: string): Promise<void> {
+    const pid = this.daemonPid;
+
+    try {
+      await this.request("daemon.shutdown", {}, EmptyResultSchema, 2_000);
+    } catch {
+      if (pid !== undefined) {
+        try {
+          process.kill(pid);
+        } catch {}
+      }
+    }
+    this.socket?.end();
+    this.resetConnection();
+    // the old daemon removes its socket in stop(); wait so the new one binds cleanly
+    const deadline = Date.now() + 5_000;
+
+    while (Date.now() < deadline && existsSync(path)) await Bun.sleep(50);
+  }
+
+  /** Reset per-connection state so a fresh dial() can reuse this client instance. */
+  private resetConnection(): void {
+    this.socket = null;
+    this.writer = null;
+    this.closed = false;
+    for (const pendingRequest of this.pending.values())
+      pendingRequest.reject(new Error("daemon connection replaced"));
+    this.pending.clear();
+  }
+
+  /** Clean any stale socket, spawn a detached daemon, and dial it until it answers. */
+  private async attachFreshDaemon(home: string, path: string): Promise<DaemonClient> {
     if (existsSync(path)) rmSync(path, { force: true });
     spawnDaemon(home);
     // Generous: a cold or loaded machine pays for a runtime start before the
@@ -179,9 +247,9 @@ export class DaemonClient implements SessionClient {
 
     while (Date.now() < deadline) {
       try {
-        await client.dial(path);
+        await this.dial(path);
 
-        return client;
+        return this;
       } catch (err) {
         lastError = err;
         await Bun.sleep(50);
@@ -213,8 +281,12 @@ export class DaemonClient implements SessionClient {
     });
     this.writer = new BackpressureWriter(this.socket);
     // Verify liveness: a dead socket file accepts connects on some platforms
-    // only to fail later, so a ping is the actual handshake.
-    await this.request("daemon.ping", {}, PingResultSchema, 2_000);
+    // only to fail later, so a ping is the actual handshake. It also carries the
+    // daemon's build version and pid, so connect() can replace a stale daemon.
+    const pong = await this.request("daemon.ping", {}, PingResultSchema, 2_000);
+
+    this.daemonVersion = pong.version;
+    this.daemonPid = pong.pid;
     // Every connection starts as a collaborator; the owner proves itself with
     // the token the daemon wrote into the home it serves, which only the home's
     // user can read. A capped role just names itself.
@@ -400,6 +472,16 @@ export class DaemonClient implements SessionClient {
       v.array(v.object({ path: v.string(), status: v.picklist(["added", "modified", "deleted"]) })),
     );
   }
+  repoDiff(cwd: string): Promise<WorkingTreeDiff> {
+    return this.request(
+      "repo.diff",
+      { cwd },
+      v.object({ patch: v.string(), files: v.array(DiffFileContentsSchema) }),
+    );
+  }
+  sessionWorkbench(cwd: string): Promise<ReviewSession> {
+    return this.request("session.workbench", { cwd }, SessionRecordSchema);
+  }
   /** Re-capture a diff session's working tree; changed=true when the patch moved and an event fired. */
   sessionRefreshDiff(id: string): Promise<{ changed: boolean }> {
     return this.request("session.refreshDiff", { id }, RefreshDiffResultSchema);
@@ -417,8 +499,17 @@ export class DaemonClient implements SessionClient {
   sessionSetSelfName(id: string, _name: string): Promise<ReviewSession> {
     return this.sessionGet(id);
   }
-  sessionResolve(id: string, verdictKind: VerdictKind, summary: string): Promise<ReviewSession> {
-    return this.request("session.resolve", { id, verdictKind, summary }, SessionRecordSchema);
+  sessionResolve(
+    id: string,
+    verdictKind: VerdictKind,
+    summary: string,
+    actionBodies?: Record<string, string>,
+  ): Promise<ReviewSession> {
+    return this.request(
+      "session.resolve",
+      { id, verdictKind, summary, actionBodies },
+      SessionRecordSchema,
+    );
   }
   sessionSubmitRevision(
     id: string,
@@ -453,14 +544,22 @@ export class DaemonClientError extends Error {
 }
 
 // A compiled binary re-execs `cueloop daemon --autostart` (idle-exits like main.ts,
-// unlike the never-exiting foreground daemon); from source, bun runs main.ts.
-export function daemonSpawnCommand(execPath: string, moduleUrl: string): string[] {
+// unlike the never-exiting foreground daemon); from source, bun runs main.ts. In
+// dev (CUELOOP_DEV_WATCH=1, source only) it runs under --watch so daemon-code edits
+// reload the daemon without a manual restart - the version handshake only catches
+// release upgrades, not same-version source changes.
+export function daemonSpawnCommand(
+  execPath: string,
+  moduleUrl: string,
+  devWatch = process.env.CUELOOP_DEV_WATCH === "1",
+): string[] {
   const compiled =
     moduleUrl.includes("$bunfs") || moduleUrl.includes("~BUN") || moduleUrl.includes("%7EBUN");
 
-  return compiled
-    ? [execPath, "daemon", "--autostart"]
-    : [execPath, "run", new URL("./main.ts", moduleUrl).pathname];
+  if (compiled) return [execPath, "daemon", "--autostart"];
+  const mainPath = new URL("./main.ts", moduleUrl).pathname;
+
+  return devWatch ? [execPath, "--watch", "run", mainPath] : [execPath, "run", mainPath];
 }
 
 function spawnDaemon(home: string): void {

package/src/daemon-version.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Version handshake: a client must never keep talking to a daemon from an
+ * earlier build (the stale-daemon-after-upgrade bug). The ping carries the
+ * daemon's version; a mismatch without autostart is a clear error, and a
+ * matching version connects normally.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DaemonServer } from "./server";
+import { DaemonClient, DaemonClientError, daemonSpawnCommand } from "./client";
+import { DAEMON_VERSION } from "./version";
+import type { Artifact, WorkspaceKey } from "@cueloop/schema";
+
+const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
+const PLAN: Artifact = { type: "plan", content: "# P\n\nBody.\n", meta: {} };
+
+let home: string;
+const servers: DaemonServer[] = [];
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-version-"));
+});
+afterEach(() => {
+  for (const runningServer of servers.splice(0)) runningServer.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+function server(version?: string): DaemonServer {
+  const daemonServer = new DaemonServer({ home, idleExitMs: 0, version });
+
+  servers.push(daemonServer);
+
+  return daemonServer;
+}
+
+describe("daemon version handshake", () => {
+  test("a stale daemon is rejected when there is nothing to replace it", async () => {
+    // Arrange - a daemon posing as an earlier build
+    server("0.0.0-stale").start();
+
+    // Act + Assert - without autostart the client cannot restart it, so it says why
+    await expect(DaemonClient.connect({ home, autostart: false })).rejects.toMatchObject({
+      code: "version_mismatch",
+    });
+    await expect(DaemonClient.connect({ home, autostart: false })).rejects.toBeInstanceOf(
+      DaemonClientError,
+    );
+  });
+
+  test("a current daemon connects and serves normally", async () => {
+    // Arrange - a daemon on this build
+    server(DAEMON_VERSION).start();
+    const client = await DaemonClient.connect({ home, autostart: false });
+
+    // Act - a round-trip proves the connection is live, not replaced
+    const created = await client.sessionCreate(WS, PLAN);
+    const listed = await client.sessionList();
+
+    // Assert
+    expect(listed.map((session) => session.id)).toContain(created.id);
+    client.close();
+  });
+});
+
+describe("daemon spawn command", () => {
+  const SOURCE_URL = "file:///repo/packages/daemon/src/client.ts";
+
+  test("from source it bun-runs main.ts", () => {
+    expect(daemonSpawnCommand("/bin/bun", SOURCE_URL, false)).toEqual([
+      "/bin/bun",
+      "run",
+      "/repo/packages/daemon/src/main.ts",
+    ]);
+  });
+
+  test("dev-watch reloads the daemon on source edits", () => {
+    expect(daemonSpawnCommand("/bin/bun", SOURCE_URL, true)).toEqual([
+      "/bin/bun",
+      "--watch",
+      "run",
+      "/repo/packages/daemon/src/main.ts",
+    ]);
+  });
+
+  test("a compiled binary re-execs its own daemon command, never --watch", () => {
+    expect(
+      daemonSpawnCommand("/usr/local/bin/cueloop", "file:///$bunfs/root/cueloop", true),
+    ).toEqual(["/usr/local/bin/cueloop", "daemon", "--autostart"]);
+  });
+});