@cueloop/daemon 0.1.0-alpha.64 → 0.1.0-alpha.66

package/src/capabilities.ts

@@ -1,31 +1,64 @@
 /**
- * Daemon role capabilities: which socket methods a connection may call. The
- * owner (the local planner) may call everything; a collaborator or a review-side
- * agent is capped to reading the session and adding annotations, so a bring-your-
- * own agent literally cannot resolve, rewrite, cut, share, or delete (ADR 0009).
- * This is the single source of truth the server dispatch enforces.
+ * Daemon roles: which primitives a connection may call. A connection is a
+ * collaborator until it proves ownership with the owner token in daemon.hello
+ * - never an owner by default. The owner (the local planner) may call every
+ * primitive; a collaborator or a review-side agent is capped to reading the
+ * session and adding comments, so a bring-your-own agent cannot resolve,
+ * rewrite, cut, share, or delete (ADR 0009). The table below is exhaustive
+ * over the primitive schemas: adding a primitive without naming its roles
+ * does not compile.
  */
 
 import * as v from "valibot";
+import type { MethodName } from "./validate";
 
 export type DaemonRole = "owner" | "collaborator" | "agent";
 
-/** Methods a non-owner role may call: read the session and annotate, plus connection plumbing. */
-const NON_OWNER_METHODS = new Set<string>([
-  "daemon.ping",
-  "daemon.hello",
-  "events.subscribe",
-  "session.get",
-  "session.list",
-  "session.wait",
-  "session.annotate",
-]);
-
-/** Whether `role` may call `method`. The owner may call anything; others are capped to read + annotate. */
-export function roleAllowsMethod(role: DaemonRole, method: string): boolean {
-  return role === "owner" || NON_OWNER_METHODS.has(method);
+/** Who may call a primitive: everyone, or the owner only. */
+type Audience = "any" | "owner";
+
+const PRIMITIVE_ROLES = {
+  "daemon.ping": "any",
+  "daemon.hello": "any",
+  "daemon.shutdown": "owner",
+  "events.subscribe": "any",
+  "session.create": "owner",
+  "session.get": "any",
+  "session.list": "any",
+  "session.wait": "any",
+  "session.annotate": "any",
+  // any role may call it; a non-owner must act on behalf of an author and stays scoped to it
+  "session.removeAnnotation": "any",
+  "session.setParticipantName": "any",
+  "session.setWorkingCopy": "owner",
+  "session.cutBlock": "owner",
+  "session.restoreBlock": "owner",
+  "session.curate": "owner",
+  "session.setViewed": "owner",
+  // the tree is the owner's: collaborators comment on the branch a share follows
+  "session.navigate": "owner",
+  "session.branch": "owner",
+  "session.switch": "owner",
+  "session.label": "owner",
+  "session.fork": "owner",
+  "session.refreshDiff": "owner",
+  "session.setShareId": "owner",
+  "session.delete": "owner",
+  "session.mergeShared": "owner",
+  "session.resolve": "owner",
+  "session.submitRevision": "owner",
+  "herdr.getTab": "owner",
+  "herdr.setTab": "owner",
+} as const satisfies Record<MethodName, Audience>;
+
+/** Whether `role` may call `method`. */
+export function roleAllowsMethod(role: DaemonRole, method: MethodName): boolean {
+  return role === "owner" || PRIMITIVE_ROLES[method] === "any";
 }
 
+/** The role a connection starts with, before any proof. */
+export const DEFAULT_ROLE: DaemonRole = "collaborator";
+
 export function asDaemonRole(value: Parameters<typeof v.safeParse>[1]): DaemonRole {
   const result = v.safeParse(v.picklist(["owner", "collaborator"]), value);
 

package/src/client.ts

@@ -1,15 +1,15 @@
 /**
- * Daemon client: the one library every consumer shares - CLI verbs, the TUI,
+ * Daemon client: the one library every consumer shares - CLI primitives, the TUI,
  * adapters, and tests. Also owns the lazy-launch story: connect() with
  * autostart spawns a detached daemon when the socket is dead, then attaches.
  */
 
-import { existsSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import * as v from "valibot";
 import type {
   Annotation,
   Artifact,
-  Identity,
+  HunkRejection,
   ReviewSession,
   VerdictKind,
   WorkspaceKey,
@@ -24,8 +24,11 @@ import {
 } from "./protocol";
 import type { DaemonRole } from "./capabilities";
 import type { HerdrTabHandle } from "./herdr-tab-store";
-import { cueloopHome, socketPath } from "./paths";
-import { SessionRecordSchema } from "./validate";
+import type { SharedMerge } from "./api";
+
+export type { SharedMerge } from "./api";
+import { cueloopHome, ownerTokenPath, socketPath } from "./paths";
+import { Params, SessionRecordSchema } from "./validate";
 
 export type { EventFrame } from "./protocol";
 
@@ -35,6 +38,8 @@ export interface ConnectOptions {
   autostart?: boolean;
   /** Capability role for this connection; a review-side agent connects capped. Defaults to owner. */
   role?: DaemonRole;
+  /** The author a non-owner connection acts as; its comments, removals, and name are bound to it. */
+  author?: string;
 }
 
 type PendingRequest = {
@@ -48,7 +53,7 @@ const RefreshDiffResultSchema = v.object({ changed: v.boolean() });
 const HerdrTabResultSchema = v.nullable(v.object({ tabId: v.string(), paneId: v.string() }));
 
 /**
- * The session verbs the review controller drives. DaemonClient is the local
+ * The session primitives the review controller drives. DaemonClient is the local
  * implementation (unix socket); the sharing gateway supplies an in-memory,
  * blob-backed one. Depending on this interface - not DaemonClient - is what
  * lets the same <App> render a local session or a decrypted share unchanged.
@@ -63,14 +68,32 @@ export interface SessionClient {
     annotation: Omit<Annotation, "createdAt">,
     authorName?: string,
   ): Promise<ReviewSession>;
+  /** Remove a comment; a non-owner connection removes only the comments of the author it is bound to. */
   sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession>;
   sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession>;
+  /** Cut the `blockIndex`-th block of the working copy. */
+  sessionCutBlock(id: string, blockIndex: number): Promise<ReviewSession>;
+  /** Re-insert the `baseBlockIndex`-th block of the submitted revision before `line` (default: the end). */
+  sessionRestoreBlock(id: string, baseBlockIndex: number, line?: number): Promise<ReviewSession>;
+  /** Replace a diff review's reject decisions; the working copy follows. */
+  sessionCurate(id: string, rejections: HunkRejection[]): Promise<ReviewSession>;
   sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession>;
-  sessionSetShareId(id: string, shareId: string): Promise<ReviewSession>;
-  sessionMergeShared(
+  /** 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,
-    incoming: { annotations: Annotation[]; participants?: Identity[] },
+    entryId: string,
+    summary?: string,
+    branch?: string,
   ): Promise<ReviewSession>;
+  /** Start a branch at the current tip and switch to it. */
+  sessionBranch(id: string, name: string): Promise<ReviewSession>;
+  sessionSwitch(id: string, branch: string): Promise<ReviewSession>;
+  /** Name the current tip as a checkpoint. */
+  sessionLabel(id: string, label: string): Promise<ReviewSession>;
+  /** Copy the current path into a new session; returns the fork. */
+  sessionFork(id: string): Promise<ReviewSession>;
+  sessionSetShareId(id: string, shareId: string): Promise<ReviewSession>;
+  sessionMergeShared(id: string, incoming: SharedMerge): Promise<ReviewSession>;
   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>;
@@ -78,6 +101,33 @@ export interface SessionClient {
   close(): void;
 }
 
+/** What a connection says about itself: its role, the owner token when it claims ownership, the author it acts as otherwise. */
+interface HelloParams {
+  role: DaemonRole;
+  token?: string;
+  author?: string;
+}
+
+/** The token as the daemon writes it: 32 random bytes in hex. */
+const OwnerTokenSchema = v.pipe(v.string(), v.trim(), v.regex(/^[0-9a-f]{64}$/));
+
+/** The owner token in `home`, or undefined when the daemon there never wrote one. */
+function readOwnerToken(home: string): string | undefined {
+  const path = ownerTokenPath(home);
+
+  if (!existsSync(path)) return undefined;
+  const parsed = v.safeParse(OwnerTokenSchema, readFileSync(path, "utf8"));
+
+  if (!parsed.success) {
+    throw new DaemonClientError(
+      "invalid_owner_token",
+      `${path} is not an owner token; restart the daemon to mint a fresh one`,
+    );
+  }
+
+  return parsed.output;
+}
+
 export class DaemonClient implements SessionClient {
   private socket: Awaited<ReturnType<typeof Bun.connect>> | null = null;
   private writer: BackpressureWriter | null = null;
@@ -86,6 +136,8 @@ export class DaemonClient implements SessionClient {
   private eventListeners = new Set<(event: EventFrame) => void>();
   private closed = false;
   private role: DaemonRole = "owner";
+  private author: string | undefined;
+  private home = cueloopHome();
 
   static async connect(options: ConnectOptions = {}): Promise<DaemonClient> {
     const home = options.home ?? cueloopHome();
@@ -93,12 +145,16 @@ export class DaemonClient implements SessionClient {
     const client = new DaemonClient();
 
     client.role = options.role ?? "owner";
+    client.author = options.author;
+    client.home = home;
     try {
       await client.dial(path);
 
       return client;
     } catch (err) {
-      if (!options.autostart) throw 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.
     if (existsSync(path)) rmSync(path, { force: true });
@@ -146,9 +202,22 @@ export class DaemonClient implements SessionClient {
     // 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);
-    // Cap this connection's role for the daemon's capability gate (owner is the default).
-    if (this.role !== "owner")
-      await this.request("daemon.hello", { role: this.role }, EmptyResultSchema, 2_000);
+    // 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.
+    await this.request("daemon.hello", this.helloParams(), EmptyResultSchema, 2_000);
+  }
+
+  private helloParams(): HelloParams {
+    if (this.role !== "owner") {
+      return this.author === undefined
+        ? { role: this.role }
+        : { role: this.role, author: this.author };
+    }
+    const token = readOwnerToken(this.home);
+
+    // a daemon from before owner tokens has no file; it still knows the bare hello
+    return token === undefined ? { role: "owner" } : { role: "owner", token };
   }
 
   onEvent(listener: (event: EventFrame) => void): () => void {
@@ -213,7 +282,7 @@ export class DaemonClient implements SessionClient {
     this.socket?.end();
   }
 
-  // ── typed verbs ─────────────────────────────
+  // ── typed primitives ─────────────────────────────
   ping(): Promise<{ pid: number }> {
     return this.request("daemon.ping", {}, PingResultSchema);
   }
@@ -248,9 +317,51 @@ export class DaemonClient implements SessionClient {
   sessionRemoveAnnotation(id: string, annotationId: string): Promise<ReviewSession> {
     return this.request("session.removeAnnotation", { id, annotationId }, SessionRecordSchema);
   }
+  /** Register a display name for a participant - a collaborator's or an agent's own, on a share or locally. */
+  sessionSetParticipantName(id: string, author: string, name: string): Promise<ReviewSession> {
+    return this.request("session.setParticipantName", { id, author, name }, SessionRecordSchema);
+  }
   sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<ReviewSession> {
     return this.request("session.setWorkingCopy", { id, workingCopy }, SessionRecordSchema);
   }
+  sessionCutBlock(id: string, blockIndex: number): Promise<ReviewSession> {
+    return this.request("session.cutBlock", { id, blockIndex }, SessionRecordSchema);
+  }
+  sessionNavigate(
+    id: string,
+    entryId: string,
+    summary?: string,
+    branch?: string,
+  ): Promise<ReviewSession> {
+    const params: v.InferInput<(typeof Params)["session.navigate"]> = { id, entryId };
+
+    if (summary !== undefined) params.summary = summary;
+    if (branch !== undefined) params.branch = branch;
+
+    return this.request("session.navigate", params, SessionRecordSchema);
+  }
+  sessionBranch(id: string, name: string): Promise<ReviewSession> {
+    return this.request("session.branch", { id, name }, SessionRecordSchema);
+  }
+  sessionSwitch(id: string, branch: string): Promise<ReviewSession> {
+    return this.request("session.switch", { id, branch }, SessionRecordSchema);
+  }
+  sessionLabel(id: string, label: string): Promise<ReviewSession> {
+    return this.request("session.label", { id, label }, SessionRecordSchema);
+  }
+  sessionFork(id: string): Promise<ReviewSession> {
+    return this.request("session.fork", { id }, SessionRecordSchema);
+  }
+  sessionRestoreBlock(id: string, baseBlockIndex: number, line?: number): Promise<ReviewSession> {
+    return this.request(
+      "session.restoreBlock",
+      line === undefined ? { id, baseBlockIndex } : { id, baseBlockIndex, line },
+      SessionRecordSchema,
+    );
+  }
+  sessionCurate(id: string, rejections: HunkRejection[]): Promise<ReviewSession> {
+    return this.request("session.curate", { id, rejections }, SessionRecordSchema);
+  }
   sessionSetViewed(id: string, viewedPaths: string[]): Promise<ReviewSession> {
     return this.request("session.setViewed", { id, viewedPaths }, SessionRecordSchema);
   }
@@ -261,10 +372,7 @@ export class DaemonClient implements SessionClient {
   sessionSetShareId(id: string, shareId: string): Promise<ReviewSession> {
     return this.request("session.setShareId", { id, shareId }, SessionRecordSchema);
   }
-  sessionMergeShared(
-    id: string,
-    incoming: { annotations: Annotation[]; participants?: Identity[] },
-  ): Promise<ReviewSession> {
+  sessionMergeShared(id: string, incoming: SharedMerge): Promise<ReviewSession> {
     return this.request("session.mergeShared", { id, ...incoming }, SessionRecordSchema);
   }
   sessionDelete(id: string): Promise<void> {

package/src/curate.ts

@@ -0,0 +1,109 @@
+/**
+ * The curated patch of a diff review: the submitted changes minus the hunks and
+ * change blocks the reviewer rejected. The daemon computes it from the
+ * session's reject decisions so the working copy every client sees is one and
+ * the same; the client only maps rows to decisions.
+ */
+
+import { diffAcceptRejectHunk, parseDiffFromFile, type FileDiffMetadata } from "@pierre/diffs";
+import {
+  unifiedDiffText,
+  type DiffFileContents,
+  type DiffFileStatus,
+  type HunkRejection,
+} from "@cueloop/schema";
+
+/**
+ * Context lines around each change. Matching git's default (3) makes the model
+ * split hunks like the rendered working-tree patch does; a row is mapped by
+ * absolute line number, never by counting hunks, so a whole-hunk reject can
+ * only ever span the model hunk it lands in.
+ */
+export const DIFF_CONTEXT = 3;
+
+/** Parse one file's full contents into a non-partial diff model. */
+export function parseFileDiff(file: DiffFileContents): FileDiffMetadata {
+  return parseDiffFromFile(
+    { name: file.path, contents: file.oldContents },
+    { name: file.path, contents: file.newContents },
+    { context: DIFF_CONTEXT },
+  );
+}
+
+/**
+ * Apply one file's rejections and return its curated patch, or null when the
+ * curated content equals the old content (every change rejected - no patch).
+ * Whole-hunk rejections supersede change-level ones for the same hunk. Because
+ * `diffAcceptRejectHunk` returns a model with the same hunk/content shape, the
+ * indices stay valid across calls; they are applied high-to-low regardless, so
+ * the order is deterministic.
+ */
+function curateFilePatch(file: DiffFileContents, rejections: HunkRejection[]): string | null {
+  let model = parseFileDiff(file);
+  const wholeHunks = new Set(
+    rejections
+      .filter((rejection) => rejection.changeIndex === undefined)
+      .map((rejection) => rejection.hunkIndex),
+  );
+
+  for (const hunkIndex of [...wholeHunks].sort((a, b) => b - a)) {
+    model = diffAcceptRejectHunk(model, hunkIndex, "reject");
+  }
+  const changeRejections = rejections
+    .filter(
+      (rejection) => rejection.changeIndex !== undefined && !wholeHunks.has(rejection.hunkIndex),
+    )
+    .sort((a, b) => b.hunkIndex - a.hunkIndex || b.changeIndex! - a.changeIndex!);
+
+  for (const rejection of changeRejections) {
+    model = diffAcceptRejectHunk(model, rejection.hunkIndex, {
+      type: "reject",
+      changeIndex: rejection.changeIndex!,
+    });
+  }
+  const curatedNew = model.additionLines.join("");
+
+  if (curatedNew === file.oldContents) return null;
+  const patch = unifiedDiffText(file.oldContents, curatedNew, file.path);
+
+  if (patch === null) return null;
+
+  return withFileStateHeaders(patch, file.path, file.status, curatedNew);
+}
+
+/**
+ * Point the diff headers at /dev/null for a created or fully-deleted file so the
+ * curated patch applies. git's status - not empty contents - decides existence,
+ * so editing an existing empty file stays a modify; a deletion whose removals
+ * were partly restored also falls back to a modify.
+ */
+function withFileStateHeaders(
+  patch: string,
+  path: string,
+  status: DiffFileStatus,
+  curatedNew: string,
+): string {
+  if (status === "added") return patch.replace(`--- a/${path}`, "--- /dev/null");
+  if (status === "deleted" && curatedNew === "") {
+    return patch.replace(`+++ b/${path}`, "+++ /dev/null");
+  }
+
+  return patch;
+}
+
+/**
+ * The curated unified-diff patch of the accepted changes across every file.
+ * Files with no net change (unchanged, or with all changes rejected) drop out.
+ */
+export function curateDiff(files: DiffFileContents[], rejections: HunkRejection[]): string {
+  const parts: string[] = [];
+
+  for (const file of files) {
+    const fileRejections = rejections.filter((rejection) => rejection.path === file.path);
+    const patch = curateFilePatch(file, fileRejections);
+
+    if (patch) parts.push(patch);
+  }
+
+  return parts.join("\n");
+}

package/src/diff-hot-reload.test.ts

@@ -100,6 +100,22 @@ describe("session.refreshDiff", () => {
     expect(events).toContain("session.updated");
   });
 
+  test("a tree move after a refresh keeps the fresh patch", async () => {
+    // Given a refreshed diff session
+    const session = await openDiffSession();
+
+    writeFileSync(join(repo, "a.ts"), "export const a = 4;\n");
+    await core.sessionRefreshDiff(session.id);
+
+    // When the owner branches off and switches back
+    core.sessionBranch(session.id, "alt");
+    const shown = core.sessionSwitch(session.id, "main");
+
+    // Then the artifact still shows the re-captured working tree, and the history has one revision
+    expect(shown.artifact.content).toContain("+export const a = 4;");
+    expect(shown.history!.entries.filter((entry) => entry.type === "revision")).toHaveLength(1);
+  });
+
   test("is a no-op for a non-diff (plan) session", async () => {
     // Given a plan session in the same workspace
     const workspace = await resolveWorkspace(repo);

package/src/herdr-pane.test.ts

@@ -196,7 +196,7 @@ describe("openHerdrPaneForReview", () => {
   });
 
   test("a recall failure (stale daemon) still opens a fresh tab", async () => {
-    // Arrange - a daemon predating the herdr-tab verbs rejects the recall
+    // Arrange - a daemon predating the herdr-tab primitives rejects the recall
     const stub = makeStub("gated-recall-fail");
     const env = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1", HERDR_BIN_PATH: stub.binPath };
     const persistence: HerdrTabPersistence = {

package/src/paths.ts

@@ -30,6 +30,11 @@ export function lockPath(home = cueloopHome()): string {
   return join(home, "cueloop.lock");
 }
 
+/** The secret a connection presents to be the owner; written by the daemon, mode 0600. */
+export function ownerTokenPath(home = cueloopHome()): string {
+  return join(home, "owner.token");
+}
+
 /** Adapter scratch: herdr tab handles keyed by session id, kept out of the core session record. */
 export function herdrTabsPath(home = cueloopHome()): string {
   return join(home, "herdr-tabs.json");

package/src/protocol.ts

@@ -21,6 +21,8 @@ export interface Response {
 export interface EventFrame {
   event: string;
   sessionId: string;
+  /** The history entry the change appended, when it appended one. */
+  entryId?: string;
 }
 
 export type Frame = Response | EventFrame;
@@ -38,6 +40,7 @@ const ResponseSchema = v.object({
 const EventFrameSchema = v.object({
   event: v.string(),
   sessionId: v.string(),
+  entryId: v.optional(v.string()),
 });
 
 export function parseRequestFrame(line: string): Request {

package/src/review.ts

@@ -18,7 +18,7 @@ import {
 import { verdictResponse } from "./api";
 import type { DaemonClient } from "./client";
 
-// Adapters and CLI verbs reach the verdict mapping through this module too,
+// Adapters and CLI primitives reach the verdict mapping through this module too,
 // so a session obtained outside a ReviewHandle maps the same way.
 export { verdictResponse };
 
@@ -35,12 +35,33 @@ async function git(args: string[], cwd: string): Promise<string | null> {
   }
 }
 
-/** Workspace key resolution: repo root + branch from the cwd. */
+/** The oldest root commit reachable from HEAD; the project key that survives moving or re-cloning the repo. */
+function earliestRootCommit(revList: string | null): string | undefined {
+  if (!revList) return undefined;
+  const roots = revList.split("\n").filter((line) => line.length > 0);
+
+  // --date-order lists newest first, so the last root is the earliest
+  return roots.at(-1);
+}
+
+/** Workspace key resolution: repo root, branch, and the project identity (root commit + remote) from the cwd. */
 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 };
+  // a shallow clone's oldest commit is the graft boundary, not the true root, so
+  // it would key a different project than a full clone - leave it unset instead
+  const shallow = (await git(["rev-parse", "--is-shallow-repository"], cwd)) === "true";
+  const rootCommit = shallow
+    ? undefined
+    : earliestRootCommit(await git(["rev-list", "--max-parents=0", "--date-order", "HEAD"], cwd));
+  const remote = await git(["remote", "get-url", "origin"], cwd);
+
+  const workspace: WorkspaceKey = { repoRoot, branch };
+  // a repo with no commits (or a shallow clone) has no reliable root, so the thread stays standalone
+  if (rootCommit) workspace.rootCommit = rootCommit;
+  if (remote) workspace.remote = remote;
+
+  return workspace;
 }
 
 function firstHeading(markdown: string): string | undefined {