@cueloop/daemon 0.1.0-alpha.82 → 0.1.0-alpha.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/daemon",
-  "version": "0.1.0-alpha.82",
+  "version": "0.1.0-alpha.84",
   "description": "The cueloop session daemon and its client: socket protocol, atomic store, resumable waits",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -38,7 +38,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/schema": "0.1.0-alpha.82",
+    "@cueloop/schema": "0.1.0-alpha.84",
     "@pierre/diffs": "^1.4.1",
     "effect": "^4.0.0-rc.115",
     "smol-toml": "^1.8.0",

package/src/api.test.ts

@@ -169,6 +169,71 @@ describe("session lifecycle", () => {
     ).toThrow("already resolved");
   });
 
+  test("Comment delivers only changed annotations and keeps the Thread pending", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    core.sessionAnnotate(session.id, {
+      id: "first",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "first note",
+    });
+
+    const commented = core.sessionSendMessage(session.id, "comment", "Interim feedback");
+
+    expect(commented.status).toBe("pending");
+    expect(commented.message!.annotations?.map((annotation) => annotation.id)).toEqual(["first"]);
+    expect(commented.message!.body).toContain("first note");
+
+    core.sessionAnnotate(session.id, {
+      id: "second",
+      kind: "comment",
+      anchor: { quote: "Context", prefix: "Plan", suffix: "Do" },
+      body: "second note",
+    });
+
+    const secondComment = core.sessionSendMessage(session.id, "comment", "Another note");
+
+    expect(secondComment.status).toBe("pending");
+    expect(secondComment.message!.annotations?.map((annotation) => annotation.id)).toEqual([
+      "second",
+    ]);
+    expect(secondComment.message!.body).not.toContain("first note");
+    expect(secondComment.message!.body).toContain("second note");
+
+    core.sessionAnnotate(session.id, {
+      id: "first",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "edited first note",
+    });
+
+    const resolved = core.sessionSendMessage(session.id, "approved", "Ready");
+
+    expect(resolved.status).toBe("resolved");
+    expect(resolved.message!.annotations?.map((annotation) => annotation.id)).toEqual(["first"]);
+    expect(resolved.message!.body).toContain("edited first note");
+    expect(resolved.message!.body).not.toContain("second note");
+  });
+
+  test("agent-side resolution does not redeliver a sent annotation", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    core.sessionAnnotate(session.id, {
+      id: "sent",
+      kind: "comment",
+      anchor: { quote: "carefully", prefix: "the thing ", suffix: "." },
+      body: "sent note",
+    });
+    core.sessionSendMessage(session.id, "comment", "Interim feedback");
+    core.sessionSubmitRevision(session.id, PLAN.content, ["sent"]);
+
+    const resolved = core.sessionSendMessage(session.id, "approved", "Ready");
+
+    expect(resolved.message!.annotations).toEqual([]);
+    expect(resolved.message!.body).not.toContain("sent note");
+  });
+
   test("working copy stores edits and clears on revert or no-op", () => {
     // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
@@ -186,6 +251,55 @@ describe("session lifecycle", () => {
     expect(core.sessionGet(session.id).workingCopy).toBeUndefined();
   });
 
+  test("character Cut provenance survives persistence and clears on an arbitrary edit", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const start = PLAN.content.indexOf("carefully");
+    const end = start + "carefully".length;
+    const workingCopy = PLAN.content.slice(0, start) + PLAN.content.slice(end);
+    const cut = { start, end, quote: "carefully" };
+
+    core.sessionSetWorkingCopy(session.id, workingCopy, [cut]);
+
+    expect(core.sessionGet(session.id).textCuts).toEqual([cut]);
+    expect(new DaemonCore(home).sessionGet(session.id).textCuts).toEqual([cut]);
+    const cutTip = core.sessionGet(session.id).history!.tips.main!;
+    const root = core.sessionGet(session.id).history!.entries[0]!.id;
+
+    core.sessionBranch(session.id, "with-cut");
+    core.sessionNavigate(session.id, root, undefined, "main");
+    expect(core.sessionGet(session.id).textCuts).toBeUndefined();
+    core.sessionSwitch(session.id, "with-cut");
+    expect(core.sessionGet(session.id).history!.tips["with-cut"]).toBe(cutTip);
+    expect(core.sessionGet(session.id).textCuts).toEqual([cut]);
+    core.sessionSetWorkingCopy(session.id, PLAN.content.replace("carefully", "safely"));
+    expect(core.sessionGet(session.id).textCuts).toBeUndefined();
+  });
+
+  test("rejects character Cut provenance that does not match the artifact", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+
+    for (const textCuts of [
+      [{ start: 0, end: 5, quote: "stale" }],
+      [{ start: PLAN.content.length - 1, end: PLAN.content.length + 1, quote: "xx" }],
+    ]) {
+      expect(() => core.sessionSetWorkingCopy(session.id, "remaining", textCuts)).toThrow(
+        "text Cuts do not match the submitted artifact and working copy",
+      );
+    }
+    expect(core.sessionGet(session.id).workingCopy).toBeUndefined();
+    expect(core.sessionGet(session.id).textCuts).toBeUndefined();
+  });
+
+  test("rejects character Cut provenance whose result differs from the working copy", () => {
+    const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const start = PLAN.content.indexOf("carefully");
+    const textCuts = [{ start, end: start + "carefully".length, quote: "carefully" }];
+
+    expect(() => core.sessionSetWorkingCopy(session.id, "different", textCuts)).toThrow(
+      "text Cuts do not match the submitted artifact and working copy",
+    );
+  });
+
   test("a thread rename sets the title, clears back to the default on empty, and survives a restart", () => {
     // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
@@ -235,8 +349,13 @@ describe("session lifecycle", () => {
   test("revision reopens the session and resets working copy + message", () => {
     // Arrange
     const session = core.sessionCreate({ workspace: WS, artifact: PLAN });
+    const start = PLAN.content.indexOf("carefully");
+    const end = start + "carefully".length;
+    const cut = { start, end, quote: "carefully" };
 
-    core.sessionSetWorkingCopy(session.id, PLAN.content + "\nedit");
+    core.sessionSetWorkingCopy(session.id, PLAN.content.slice(0, start) + PLAN.content.slice(end), [
+      cut,
+    ]);
     core.sessionSendMessage(session.id, "changes_requested", "redo");
 
     // Act
@@ -246,6 +365,7 @@ describe("session lifecycle", () => {
     expect(revised.status).toBe("pending");
     expect(revised.message).toBeNull();
     expect(revised.workingCopy).toBeUndefined();
+    expect(revised.textCuts).toBeUndefined();
     expect(revised.revisions.length).toBe(2);
     expect(revised.artifact.content).toBe("# Plan v2\n");
   });

package/src/api.ts

@@ -8,6 +8,7 @@
 import {
   SCHEMA_VERSION,
   appendEntry,
+  applyTextCuts,
   applyPathView,
   createBranch,
   cutBlock,
@@ -44,6 +45,7 @@ import {
   type Delivery,
   type PendingDelivery,
   type Thread,
+  type TextCut,
   type SessionHistory,
   type Message,
   type MessageOutcome,
@@ -69,6 +71,29 @@ import { listProjectFiles, readProjectFile } from "./project-files";
 import { resolveWorkspace } from "./thread-review";
 import { DaemonError } from "./errors";
 
+/** Reviewer-controlled fields that make an annotation new or edited for delivery. */
+function annotationDeliveryFingerprint(annotation: Annotation | undefined): string {
+  if (!annotation) return "";
+
+  return JSON.stringify({
+    kind: annotation.kind,
+    anchor: {
+      quote: annotation.anchor.quote,
+      prefix: annotation.anchor.prefix,
+      suffix: annotation.anchor.suffix,
+      blockIndex: annotation.anchor.blockIndex,
+      endBlockIndex: annotation.anchor.endBlockIndex,
+      start: annotation.anchor.start,
+      end: annotation.anchor.end,
+      selector: annotation.anchor.selector,
+    },
+    target: annotation.target,
+    body: annotation.body,
+    author: annotation.author,
+    replyTo: annotation.replyTo,
+  });
+}
+
 /** What a share hands back: the notes and names it collected, and the removals it recorded. */
 export interface SharedMerge {
   annotations: Annotation[];
@@ -445,9 +470,11 @@ export class DaemonCore {
   }
 
   /** The reviewer's working copy; undefined clears it (revert all edits). */
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Thread {
+  sessionSetWorkingCopy(id: string, workingCopy: string | undefined, textCuts?: TextCut[]): Thread {
     const session = this.mutable(id);
-    const entryId = this.applyWorkingCopy(session, workingCopy);
+
+    if (textCuts?.length) this.assertTextCuts(session.artifact.content, workingCopy, textCuts);
+    const entryId = this.applyWorkingCopy(session, workingCopy, textCuts);
 
     this.store.upsert(session);
     this.emit("session.updated", id, entryId);
@@ -455,6 +482,32 @@ export class DaemonCore {
     return session;
   }
 
+  private assertTextCuts(
+    source: string,
+    workingCopy: string | undefined,
+    textCuts: readonly TextCut[],
+  ): void {
+    let previousEnd = 0;
+    const valid = textCuts.every((cut) => {
+      const matches =
+        cut.start >= previousEnd &&
+        cut.end > cut.start &&
+        cut.end <= source.length &&
+        source.slice(cut.start, cut.end) === cut.quote;
+
+      previousEnd = cut.end;
+
+      return matches;
+    });
+
+    if (!valid || workingCopy === undefined || applyTextCuts(source, textCuts) !== workingCopy) {
+      throw new DaemonError(
+        "invalid_params",
+        "text Cuts do not match the submitted artifact and working copy",
+      );
+    }
+  }
+
   /**
    * The guided walk's viewed marks. Merge-additive: walking only ever adds
    * marks, so concurrent or stale clients converge instead of overwriting
@@ -755,16 +808,29 @@ export class DaemonCore {
   ): Thread {
     const session = this.mutable(id);
     const sentAt = new Date().toISOString();
+    const sentAnnotations = new Map(
+      (session.history?.entries ?? [])
+        .filter((entry) => entry.type === "message")
+        .flatMap((entry) => (entry.type === "message" ? (entry.message.annotations ?? []) : []))
+        .map((annotation) => [annotation.id, annotation]),
+    );
+    const annotations = session.annotations.filter(
+      (annotation) =>
+        !isAddressed(annotation) &&
+        annotationDeliveryFingerprint(sentAnnotations.get(annotation.id)) !==
+          annotationDeliveryFingerprint(annotation),
+    );
     const message: Message = {
       id: newMessageId(),
       outcome,
       summary,
-      body: feedbackForSession(session, outcome, summary, actionBodies),
+      body: feedbackForSession(session, outcome, summary, actionBodies, annotations),
+      annotations,
       sentAt,
     };
 
     session.message = message;
-    session.status = "resolved";
+    session.status = outcome === "comment" ? "pending" : "resolved";
     const entryId = this.record(session, {
       type: "message",
       message,
@@ -772,13 +838,18 @@ export class DaemonCore {
     });
     this.store.upsert(session);
     this.reconcileDeliveries(session);
+    this.emit("message.sent", id, entryId);
+    if (outcome === "comment") {
+      this.emit("session.updated", id, entryId);
+
+      return session;
+    }
     // a resolved diff review is frozen; stop hot-reloading its working tree
     this.untrackLiveDiffSession(session);
     const parked = this.waiters.get(id) ?? [];
 
     this.waiters.delete(id);
     for (const parkedWaiter of parked) parkedWaiter(session);
-    this.emit("message.sent", id, entryId);
     this.emit("inbox.changed", id);
 
     return session;
@@ -815,6 +886,7 @@ export class DaemonCore {
       createdAt: now,
     });
     delete session.workingCopy;
+    delete session.textCuts;
     session.message = null;
     session.status = "pending";
 
@@ -1063,25 +1135,35 @@ export class DaemonCore {
    * Set or clear the working copy and, when the reviewer's text changed, record
    * it as a reviewer revision on the current branch. Returns that entry's id.
    */
-  private applyWorkingCopy(session: Thread, workingCopy: string | undefined): string | undefined {
+  private applyWorkingCopy(
+    session: Thread,
+    workingCopy: string | undefined,
+    textCuts?: TextCut[],
+  ): string | undefined {
     const before = session.workingCopy ?? session.artifact.content;
     const next =
       workingCopy === undefined || workingCopy === session.artifact.content
         ? undefined
         : workingCopy;
 
+    if (textCuts?.length) session.textCuts = textCuts;
+    else delete session.textCuts;
     if (next === undefined) delete session.workingCopy;
     else session.workingCopy = next;
     const after = next ?? session.artifact.content;
 
     if (after === before) return undefined;
 
-    return this.record(session, {
+    const revision: Extract<NewEntry, { type: "revision" }> = {
       type: "revision",
       by: "reviewer",
       content: after,
       createdAt: new Date().toISOString(),
-    });
+    };
+
+    if (textCuts?.length) revision.textCuts = textCuts;
+
+    return this.record(session, revision);
   }
 
   /** The session's history; a record without a revision has none and cannot be moved through. */

package/src/client.ts

@@ -31,6 +31,7 @@ import type {
   PendingDelivery,
   MessageOutcome,
   WorkspaceKey,
+  TextCut,
 } from "@cueloop/schema";
 import {
   BackpressureWriter,
@@ -77,7 +78,7 @@ type PendingRequest = {
 
 const EmptyResultSchema = v.object({});
 // 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
+// undefined, which never equals this build.
 const PingResultSchema = v.object({ pid: v.number(), version: v.optional(v.string()) });
 const RefreshDiffResultSchema = v.object({ changed: v.boolean() });
 const HerdrThreadSurfaceResultSchema = v.nullable(
@@ -113,7 +114,11 @@ export interface ThreadClient {
   ): Promise<Thread>;
   /** Remove a comment; a non-owner connection removes only the comments of the author it is bound to. */
   sessionRemoveAnnotation(id: string, annotationId: string): Promise<Thread>;
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<Thread>;
+  sessionSetWorkingCopy(
+    id: string,
+    workingCopy: string | undefined,
+    textCuts?: TextCut[],
+  ): Promise<Thread>;
   /** Cut the `blockIndex`-th block of the working copy. */
   sessionCutBlock(id: string, blockIndex: number): Promise<Thread>;
   /** Re-insert the `baseBlockIndex`-th block of the submitted revision before `line` (default: the end). */
@@ -180,6 +185,7 @@ export interface ThreadClient {
 /** 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;
+  clientVersion: string;
   token?: string;
   author?: string;
 }
@@ -209,9 +215,8 @@ export class DaemonClient implements ThreadClient {
   private writer: BackpressureWriter | null = null;
   private connectionEpoch = 0;
   private pending = new Map<number, PendingRequest>();
-  /** The connected daemon's build version and pid, learned from the ping handshake. */
+  /** The connected daemon's build version, learned from the ping handshake. */
   private daemonVersion: string | undefined;
-  private daemonPid: number | undefined;
   private nextId = 1;
   private eventListeners = new Set<(event: EventFrame) => void>();
   private disconnectListeners = new Set<() => void>();
@@ -230,52 +235,25 @@ export class DaemonClient implements ThreadClient {
     client.home = home;
     try {
       await client.dial(path);
-      // 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, absent, or just-replaced: let the new daemon own socket cleanup.
-    return client.attachFreshDaemon(home, path);
-  }
+      const daemonVersion = client.daemonVersion ?? "unknown";
 
-  /**
-   * 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 - the next daemon reclaims stale socket
-   * and lock files after it takes ownership.
-   */
-  private async stopStaleDaemon(path: string): Promise<void> {
-    const pid = this.daemonPid;
+      client.close();
+      throw new DaemonClientError(
+        "version_mismatch",
+        `daemon is version ${daemonVersion}, but this client is ${DAEMON_VERSION}; align cueloop versions before restarting the daemon`,
+      );
+    } catch (err) {
+      // Autostart repairs an unavailable socket, never a live incompatible daemon.
+      if (!options.autostart || err instanceof DaemonClientError) {
+        client.close();
 
-    try {
-      await this.request("daemon.shutdown", {}, EmptyResultSchema, 2_000);
-    } catch {
-      if (pid !== undefined) {
-        try {
-          process.kill(pid);
-        } catch {}
+        throw err;
       }
     }
-    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 sleep(50);
+    // Socket dead or absent: let the new daemon own stale socket cleanup.
+    return client.attachFreshDaemon(home, path);
   }
 
   /** Reset per-connection state so a fresh dial() can reuse this client instance. */
@@ -383,11 +361,10 @@ export class DaemonClient implements ThreadClient {
     }
     // Verify liveness: a dead socket file accepts connects on some platforms
     // 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.
+    // daemon's build version, so connect() can reject incompatible clients.
     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.
@@ -397,13 +374,15 @@ export class DaemonClient implements ThreadClient {
   private helloParams(): HelloParams {
     if (this.role !== "owner") {
       return this.author === undefined
-        ? { role: this.role }
-        : { role: this.role, author: this.author };
+        ? { role: this.role, clientVersion: DAEMON_VERSION }
+        : { role: this.role, clientVersion: DAEMON_VERSION, 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 };
+    return token === undefined
+      ? { role: "owner", clientVersion: DAEMON_VERSION }
+      : { role: "owner", clientVersion: DAEMON_VERSION, token };
   }
 
   onEvent(listener: (event: EventFrame) => void): () => void {
@@ -521,8 +500,16 @@ export class DaemonClient implements ThreadClient {
   sessionSetParticipantName(id: string, author: string, name: string): Promise<Thread> {
     return this.request("session.setParticipantName", { id, author, name }, ThreadRecordSchema);
   }
-  sessionSetWorkingCopy(id: string, workingCopy: string | undefined): Promise<Thread> {
-    return this.request("session.setWorkingCopy", { id, workingCopy }, ThreadRecordSchema);
+  sessionSetWorkingCopy(
+    id: string,
+    workingCopy: string | undefined,
+    textCuts?: TextCut[],
+  ): Promise<Thread> {
+    return this.request(
+      "session.setWorkingCopy",
+      { id, workingCopy, textCuts },
+      ThreadRecordSchema,
+    );
   }
   sessionCutBlock(id: string, blockIndex: number): Promise<Thread> {
     return this.request("session.cutBlock", { id, blockIndex }, ThreadRecordSchema);

package/src/daemon-version.test.ts

@@ -6,12 +6,13 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import { mkdtempSync, readFileSync, 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 { pidPath } from "./paths";
 import type { Artifact, WorkspaceKey } from "@cueloop/schema";
 
 const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
@@ -29,7 +30,12 @@ afterEach(() => {
 });
 
 function server(version?: string): DaemonServer {
-  const daemonServer = new DaemonServer({ home, idleExitMs: 0, version });
+  const daemonServer = new DaemonServer({
+    home,
+    idleExitMs: 0,
+    version,
+    onIdleExit: () => {},
+  });
 
   servers.push(daemonServer);
 
@@ -50,6 +56,49 @@ describe("daemon version handshake", () => {
     );
   });
 
+  test("autostart never replaces a live daemon from another version", async () => {
+    const liveServer = server("0.1.0-alpha.81");
+
+    liveServer.start();
+    const session = liveServer.core.sessionCreate({ workspace: WS, artifact: PLAN });
+    let replacement: DaemonClient | undefined;
+    let connectionError: unknown;
+
+    try {
+      replacement = await DaemonClient.connect({ home, autostart: true });
+    } catch (error) {
+      connectionError = error;
+    }
+
+    replacement?.close();
+    expect(connectionError).toBeInstanceOf(DaemonClientError);
+    expect(connectionError).toMatchObject({ code: "version_mismatch" });
+    expect(readFileSync(pidPath(home), "utf8")).toBe(String(process.pid));
+    expect(liveServer.core.sessionGet(session.id).id).toBe(session.id);
+  });
+
+  test("a rejected client releases its connection so the daemon can become idle", async () => {
+    let idleExited = false;
+    const liveServer = new DaemonServer({
+      home,
+      idleExitMs: 50,
+      version: "0.1.0-alpha.81",
+      onIdleExit: () => {
+        idleExited = true;
+      },
+    });
+
+    servers.push(liveServer);
+    liveServer.start();
+
+    await expect(DaemonClient.connect({ home, autostart: true })).rejects.toMatchObject({
+      code: "version_mismatch",
+    });
+    await Bun.sleep(100);
+
+    expect(idleExited).toBe(true);
+  });
+
   test("a current daemon connects and serves normally", async () => {
     // Arrange - a daemon on this build
     server(DAEMON_VERSION).start();

package/src/harness-delivery.test.ts

@@ -34,6 +34,23 @@ function createPlan(instance: DaemonCore) {
 }
 
 describe("durable harness delivery", () => {
+  test("delivers Comment without resolving the Thread", () => {
+    const instance = core();
+    const thread = createPlan(instance);
+    const binding = instance.harnessBind({
+      threadId: thread.id,
+      harness: "fake",
+      harnessSessionId: "fake_1",
+    });
+
+    const sent = instance.sessionSendMessage(thread.id, "comment", "Interim note.");
+    const pending = instance.deliveryPending(binding.id);
+
+    expect(sent.status).toBe("pending");
+    expect(pending).toHaveLength(1);
+    expect(pending[0]!.message.outcome).toBe("comment");
+  });
+
   test("reload finds only bindings for the active harness conversation", () => {
     const first = core();
     const thread = createPlan(first);

package/src/server.test.ts

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import * as v from "valibot";
 import { DaemonServer } from "./server";
 import { DaemonClient, DaemonClientError } from "./client";
+import { DAEMON_VERSION } from "./version";
 import type { Artifact, WorkspaceKey } from "@cueloop/schema";
 
 const WS: WorkspaceKey = { repoRoot: "/repo", branch: "main" };
@@ -413,7 +414,15 @@ describe("ownership is proven, never declared", () => {
     // Act: the token the daemon wrote into its home
     const token = readFileSync(join(home, "owner.token"), "utf8").trim();
 
-    expect((await raw.call("daemon.hello", { role: "owner", token })).error).toBeUndefined();
+    expect(
+      (
+        await raw.call("daemon.hello", {
+          role: "owner",
+          token,
+          clientVersion: DAEMON_VERSION,
+        })
+      ).error,
+    ).toBeUndefined();
 
     // Assert: owner primitives open up
     const created = await raw.call("session.create", { workspace: WS, artifact: PLAN });
@@ -422,6 +431,18 @@ describe("ownership is proven, never declared", () => {
     raw.close();
   });
 
+  test("an older owner cannot shut down a newer daemon", async () => {
+    const raw = await rawConnection();
+    const token = readFileSync(join(home, "owner.token"), "utf8").trim();
+
+    expect((await raw.call("daemon.hello", { role: "owner", token })).error?.code).toBe(
+      "version_mismatch",
+    );
+    expect((await raw.call("daemon.shutdown", {})).error?.code).toBe("forbidden");
+    expect((await raw.call("daemon.ping", {})).error).toBeUndefined();
+    raw.close();
+  });
+
   test("a refused handshake reaches the caller and leaves the live daemon's socket alone", async () => {
     // Arrange: a token file that is not what the daemon minted
     const tokenPath = join(home, "owner.token");

package/src/server.ts

@@ -297,6 +297,13 @@ export class DaemonServer {
       if (params.role === "owner" && params.token !== this.ownerToken) {
         throw new DaemonError("forbidden", "owner token required");
       }
+      if (params.clientVersion !== this.version) {
+        throw new DaemonError(
+          "version_mismatch",
+          `daemon is version ${this.version}, but this client is ${params.clientVersion ?? "unknown"}; align cueloop versions before restarting the daemon`,
+        );
+      }
+
       connection.role = params.role;
       // identity is bound once, here; a non-owner never names it per call
       if (params.role !== "owner" && params.author !== undefined) connection.author = params.author;
@@ -370,7 +377,7 @@ export class DaemonServer {
     "session.setWorkingCopy": (_connection, request) => {
       const params = parseParams("session.setWorkingCopy", request.params);
 
-      return this.core.sessionSetWorkingCopy(params.id, params.workingCopy);
+      return this.core.sessionSetWorkingCopy(params.id, params.workingCopy, params.textCuts);
     },
     "session.cutBlock": (_connection, request) => {
       const params = parseParams("session.cutBlock", request.params);

package/src/validate.test.ts

@@ -76,6 +76,30 @@ describe("parseParams", () => {
     }
   });
 
+  test.each([
+    [
+      [
+        { start: 2, end: 4, quote: "ab" },
+        { start: 1, end: 2, quote: "c" },
+      ],
+    ],
+    [
+      [
+        { start: 1, end: 4, quote: "abc" },
+        { start: 3, end: 5, quote: "de" },
+      ],
+    ],
+    [[{ start: 1, end: 4, quote: "ab" }]],
+  ])("rejects malformed text Cut provenance", (textCuts) => {
+    expect(() =>
+      parseParams("session.setWorkingCopy", {
+        id: "ses_1",
+        workingCopy: "remaining",
+        textCuts,
+      }),
+    ).toThrow("text Cuts must be ordered, non-overlapping, and match their quote lengths");
+  });
+
   test("rejects an unknown artifact type", () => {
     expect(() =>
       parseParams("session.create", {
@@ -224,6 +248,7 @@ describe("wire pins", () => {
     outcome: "approved",
     summary: "",
     body: "",
+    annotations: [fullAnnotation],
     sentAt: "now",
   };
   const fullRevision: Required<Revision> = { revision: 1, content: "# P", submittedAt: "now" };
@@ -276,7 +301,8 @@ describe("wire pins", () => {
     shelvedAnnotations: [fullAnnotation],
     parentSessionId: "ses_0",
     shareBranch: "main",
-    workingCopy: "# P edited",
+    workingCopy: "# ",
+    textCuts: [{ start: 2, end: 3, quote: "P" }],
     viewedPaths: ["src/a.ts"],
     message: fullMessage,
     status: "pending",
@@ -320,6 +346,20 @@ describe("wire pins", () => {
     if (!parsed.ok) expect(parsed.error).toContain("history:");
   });
 
+  test("a persisted Thread with stale text Cut provenance is refused", () => {
+    const result = validateThreadRecord({
+      ...fullSession,
+      workingCopy: "# P",
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error).toContain(
+        "text Cuts do not match the submitted artifact and working copy",
+      );
+    }
+  });
+
   test("schema key sets match the schema types", () => {
     expect(entryKeys(WorkspaceSchema)).toEqual(keys(fullWorkspace));
     expect(entryKeys(ArtifactMetaSchema)).toEqual(keys(fullMeta));

package/src/validate.ts

@@ -12,6 +12,7 @@
 import * as v from "valibot";
 import {
   ARTIFACT_TYPES,
+  MESSAGE_OUTCOMES,
   WORKFLOW_KINDS,
   SCHEMA_VERSION,
   type Anchor,
@@ -22,6 +23,7 @@ import {
   type DiffFileContents,
   type Identity,
   type Thread,
+  type TextCut,
   type HunkRejection,
   type HarnessBinding,
   type Delivery,
@@ -33,6 +35,7 @@ import {
   validateHistory,
   type Message,
   type WorkspaceKey,
+  applyTextCuts,
 } from "@cueloop/schema";
 import { DaemonError } from "./errors";
 import type { Request } from "./protocol";
@@ -48,6 +51,25 @@ type EntriesOf<T> = { [K in keyof T]-?: v.GenericSchema<any, any> };
 
 const NonEmpty = v.pipe(v.string(), v.minLength(1));
 
+const TextCutSchema = v.object({
+  start: v.pipe(v.number(), v.integer(), v.minValue(0)),
+  end: v.pipe(v.number(), v.integer(), v.minValue(1)),
+  quote: NonEmpty,
+} satisfies EntriesOf<TextCut>);
+
+const TextCutsSchema = v.pipe(
+  v.array(TextCutSchema),
+  v.check(
+    (cuts) =>
+      cuts.every(
+        (cut, index) =>
+          cut.end - cut.start === cut.quote.length &&
+          (index === 0 || cuts[index - 1]!.end <= cut.start),
+      ),
+    "text Cuts must be ordered, non-overlapping, and match their quote lengths",
+  ),
+);
+
 export const WorkspaceSchema = v.object({
   repoRoot: NonEmpty,
   branch: NonEmpty,
@@ -196,7 +218,11 @@ export const Params = {
   }),
   "session.removeAnnotation": v.object({ id: SessionId, annotationId: NonEmpty }),
   "session.setParticipantName": v.object({ id: SessionId, author: NonEmpty, name: NonEmpty }),
-  "session.setWorkingCopy": v.object({ id: SessionId, workingCopy: v.optional(v.string()) }),
+  "session.setWorkingCopy": v.object({
+    id: SessionId,
+    workingCopy: v.optional(v.string()),
+    textCuts: v.optional(TextCutsSchema),
+  }),
   "session.cutBlock": v.object({
     id: SessionId,
     blockIndex: v.pipe(v.number(), v.integer(), v.minValue(0)),
@@ -252,7 +278,7 @@ export const Params = {
   }),
   "session.sendMessage": v.object({
     id: SessionId,
-    outcome: v.picklist(["approved", "changes_requested"]),
+    outcome: v.picklist(MESSAGE_OUTCOMES),
     summary: v.optional(v.string(), ""),
     actionBodies: v.optional(v.record(v.string(), v.string())),
   }),
@@ -282,6 +308,7 @@ export const Params = {
   // the owner token proves ownership; without it a request for owner stays a collaborator
   "daemon.hello": v.object({
     role: v.picklist(["owner", "collaborator", "agent"]),
+    clientVersion: v.optional(v.string()),
     token: v.optional(v.string()),
     // the author a non-owner acts as, bound once for the connection
     author: v.optional(NonEmpty),
@@ -335,9 +362,10 @@ export const RevisionSchema = v.object({
 
 export const MessageSchema = v.object({
   id: NonEmpty,
-  outcome: v.picklist(["approved", "changes_requested"]),
+  outcome: v.picklist(MESSAGE_OUTCOMES),
   summary: v.string(),
   body: v.string(),
+  annotations: v.optional(v.array(FullAnnotationSchema)),
   sentAt: v.string(),
 } satisfies EntriesOf<Message>);
 
@@ -359,6 +387,7 @@ export const SessionEntrySchema = v.variant("type", [
     type: v.literal("revision"),
     by: v.picklist(["agent", "reviewer"]),
     content: v.string(),
+    textCuts: v.optional(TextCutsSchema),
   }),
   v.object({ ...EntryBaseEntries, type: v.literal("comment"), annotationId: NonEmpty }),
   v.object({ ...EntryBaseEntries, type: v.literal("comment-removed"), annotationId: NonEmpty }),
@@ -388,39 +417,53 @@ export const SessionHistorySchema = v.pipe(
 );
 
 /** Persisted records are validated on recovery: a bad file is skipped, not fatal. */
-export const ThreadRecordSchema = v.object({
-  schemaVersion: v.literal(SCHEMA_VERSION),
-  id: NonEmpty,
-  workspace: WorkspaceSchema,
-  artifact: ArtifactSchema,
-  revisions: v.array(RevisionSchema),
-  annotations: v.array(FullAnnotationSchema),
-  history: v.optional(SessionHistorySchema),
-  curation: v.optional(
-    v.array(
-      v.object({
-        path: NonEmpty,
-        hunkIndex: v.number(),
-        changeIndex: v.optional(v.number()),
-      } satisfies EntriesOf<HunkRejection>),
+export const ThreadRecordSchema = v.pipe(
+  v.object({
+    schemaVersion: v.literal(SCHEMA_VERSION),
+    id: NonEmpty,
+    workspace: WorkspaceSchema,
+    artifact: ArtifactSchema,
+    revisions: v.array(RevisionSchema),
+    annotations: v.array(FullAnnotationSchema),
+    history: v.optional(SessionHistorySchema),
+    curation: v.optional(
+      v.array(
+        v.object({
+          path: NonEmpty,
+          hunkIndex: v.number(),
+          changeIndex: v.optional(v.number()),
+        } satisfies EntriesOf<HunkRejection>),
+      ),
     ),
-  ),
-  workingCopy: v.optional(v.string()),
-  viewedPaths: v.optional(v.array(v.string())),
-  message: v.nullable(MessageSchema),
-  status: v.picklist(["pending", "resolved"]),
-  createdAt: v.string(),
-  shelvedAnnotations: v.optional(v.array(FullAnnotationSchema)),
-  parentSessionId: v.optional(v.string()),
-  shares: v.optional(v.array(ShareLinkSchema)),
-  shareId: v.optional(v.string()),
-  shareBranch: v.optional(v.string()),
-  owner: v.optional(v.string()),
-  access: v.optional(
-    v.object({ githubLogins: v.array(NonEmpty) } satisfies EntriesOf<ShareAccess>),
-  ),
-  participants: v.optional(v.array(IdentitySchema)),
-} satisfies EntriesOf<Thread>);
+    workingCopy: v.optional(v.string()),
+    textCuts: v.optional(TextCutsSchema),
+    viewedPaths: v.optional(v.array(v.string())),
+    message: v.nullable(MessageSchema),
+    status: v.picklist(["pending", "resolved"]),
+    createdAt: v.string(),
+    shelvedAnnotations: v.optional(v.array(FullAnnotationSchema)),
+    parentSessionId: v.optional(v.string()),
+    shares: v.optional(v.array(ShareLinkSchema)),
+    shareId: v.optional(v.string()),
+    shareBranch: v.optional(v.string()),
+    owner: v.optional(v.string()),
+    access: v.optional(
+      v.object({ githubLogins: v.array(NonEmpty) } satisfies EntriesOf<ShareAccess>),
+    ),
+    participants: v.optional(v.array(IdentitySchema)),
+  } satisfies EntriesOf<Thread>),
+  v.rawCheck(({ dataset, addIssue }) => {
+    if (!dataset.typed || !dataset.value.textCuts?.length) return;
+    const { artifact, textCuts, workingCopy } = dataset.value;
+    const matchesSource = textCuts.every(
+      (cut) => artifact.content.slice(cut.start, cut.end) === cut.quote,
+    );
+
+    if (!matchesSource || workingCopy !== applyTextCuts(artifact.content, textCuts)) {
+      addIssue({ message: "text Cuts do not match the submitted artifact and working copy" });
+    }
+  }),
+);
 
 export function validateThreadRecord(
   raw: Parameters<typeof v.safeParse>[1],