@cueloop/schema 0.1.0-alpha.33 → 0.1.0-alpha.35

package/package.json

@@ -1,7 +1,21 @@
 {
   "name": "@cueloop/schema",
-  "version": "0.1.0-alpha.33",
+  "version": "0.1.0-alpha.35",
+  "description": "The ReviewSession primitive: types, markdown block model, quote-primary anchors, feedback serialization",
+  "homepage": "https://github.com/mmurakaru/cueloop#readme",
+  "bugs": {
+    "url": "https://github.com/mmurakaru/cueloop/issues"
+  },
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mmurakaru/cueloop.git",
+    "directory": "packages/schema"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
@@ -9,21 +23,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
   "engines": {
     "bun": ">=1.3.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mmurakaru/cueloop.git",
-    "directory": "packages/schema"
-  },
-  "homepage": "https://github.com/mmurakaru/cueloop#readme",
-  "bugs": {
-    "url": "https://github.com/mmurakaru/cueloop/issues"
-  },
-  "description": "The ReviewSession primitive: types, markdown block model, quote-primary anchors, feedback serialization"
-}
+  }
+}

package/src/anchor.test.ts

@@ -54,7 +54,9 @@ describe("anchor cascade", () => {
     const blocks = blocksOf(DOC);
     const contextBlockIndex = blocks.findIndex((block) => block.text.startsWith("Review sessions"));
     const anchor = makeAnchor(blocks, contextBlockIndex, 0, 15);
-    const edited = blocksOf(DOC.replace("Review sessions currently", "PREFIX. Review sessions now"));
+    const edited = blocksOf(
+      DOC.replace("Review sessions currently", "PREFIX. Review sessions now"),
+    );
 
     // Act
     const resolved = resolveAnchor(anchor, edited)!;
@@ -62,7 +64,9 @@ describe("anchor cascade", () => {
     // Assert
     const editedBlockIndex = edited.findIndex((block) => block.text.includes("Review sessions"));
     expect(resolved.blockIndex).toBe(editedBlockIndex);
-    expect(edited[resolved.blockIndex]!.text.slice(resolved.start, resolved.end)).toBe("Review sessions");
+    expect(edited[resolved.blockIndex]!.text.slice(resolved.start, resolved.end)).toBe(
+      "Review sessions",
+    );
   });
 
   test("prefix/suffix selectors disambiguate repeated quotes", () => {
@@ -72,7 +76,12 @@ describe("anchor cascade", () => {
     // anchor on the SECOND "Sessions are written" occurrence
     const text = blocks[storageBlockIndex]!.text;
     const second = text.indexOf("Sessions are written", text.indexOf("Sessions are written") + 1);
-    const anchor = makeAnchor(blocks, storageBlockIndex, second, second + "Sessions are written".length);
+    const anchor = makeAnchor(
+      blocks,
+      storageBlockIndex,
+      second,
+      second + "Sessions are written".length,
+    );
 
     // Act
     const resolved = resolveAnchor(anchor, blocks)!;
@@ -96,8 +105,14 @@ describe("anchor cascade", () => {
 
   test("trimmed-quote fallback marks the resolution approximate", () => {
     // Arrange
-    const blocks = blocksOf("some text here");
-    const anchor = { quote: " text ", prefix: "some", suffix: "here", blockIndex: 0, start: 4, end: 10 };
+    const anchor = {
+      quote: " text ",
+      prefix: "some",
+      suffix: "here",
+      blockIndex: 0,
+      start: 4,
+      end: 10,
+    };
     const edited = blocksOf("some\ntext\nhere");
     // " text " (with spaces) is gone, "text" survives
 
@@ -114,7 +129,9 @@ describe("anchor cascade", () => {
     const blocks = blocksOf(DOC);
     const contextBlockIndex = blocks.findIndex((block) => block.text.startsWith("Review sessions"));
     const anchor = makeAnchor(blocks, contextBlockIndex, 0, 15);
-    const edited = blocksOf(DOC.replace(/Review sessions[^\n]*\n[^\n]*/, "Completely different text."));
+    const edited = blocksOf(
+      DOC.replace(/Review sessions[^\n]*\n[^\n]*/, "Completely different text."),
+    );
 
     // Assert
     expect(resolveAnchor(anchor, edited)).toBeNull();

package/src/anchor.ts

@@ -22,7 +22,12 @@ export interface ResolvedAnchor {
   approximate: boolean;
 }
 
-export function makeAnchor(blocks: Block[], blockIndex: number, start: number, end: number): Anchor {
+export function makeAnchor(
+  blocks: Block[],
+  blockIndex: number,
+  start: number,
+  end: number,
+): Anchor {
   const blockText = blocks[blockIndex]?.text ?? "";
   return {
     quote: blockText.slice(start, end),
@@ -42,15 +47,28 @@ function findCandidates(anchor: Anchor, blocks: Block[], quote: string): Candida
   const candidates: Candidate[] = [];
   blocks.forEach((block, blockIndex) => {
     const text = block.text;
-    for (let matchStart = text.indexOf(quote); matchStart !== -1; matchStart = text.indexOf(quote, matchStart + 1)) {
+    for (
+      let matchStart = text.indexOf(quote);
+      matchStart !== -1;
+      matchStart = text.indexOf(quote, matchStart + 1)
+    ) {
       const prefix = text.slice(Math.max(0, matchStart - ANCHOR_CONTEXT_CHARS), matchStart);
-      const suffix = text.slice(matchStart + quote.length, matchStart + quote.length + ANCHOR_CONTEXT_CHARS);
+      const suffix = text.slice(
+        matchStart + quote.length,
+        matchStart + quote.length + ANCHOR_CONTEXT_CHARS,
+      );
       let score = 0;
       if (prefix === anchor.prefix) score += 2;
       if (suffix === anchor.suffix) score += 2;
       if (anchor.blockIndex === blockIndex) score += 1;
       if (anchor.blockIndex === blockIndex && anchor.start === matchStart) score += 1;
-      candidates.push({ blockIndex, start: matchStart, end: matchStart + quote.length, approximate: false, score });
+      candidates.push({
+        blockIndex,
+        start: matchStart,
+        end: matchStart + quote.length,
+        approximate: false,
+        score,
+      });
     }
   });
   return candidates;

package/src/diff.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { lcsDiff, unifiedDiff, unifiedDiffText, editStats, wordDiff } from "./diff";
+import { lcsDiff, unifiedDiff, unifiedDiffText, editStats } from "./diff";
 
 describe("unifiedDiff", () => {
   test("equal inputs return null, not an empty diff", () => {
@@ -72,23 +72,14 @@ describe("editStats", () => {
   });
 });
 
-describe("wordDiff", () => {
-  test("preserves whitespace tokens and reconstructs both sides", () => {
-    // Act
-    const ops = wordDiff("the quick brown fox", "the slow brown foxes");
-
-    // Assert
-    const oldSide = ops.filter((op) => op.kind !== "add").map((op) => op.oldValue).join("");
-    const newSide = ops.filter((op) => op.kind !== "del").map((op) => op.newValue).join("");
-    expect(oldSide).toBe("the quick brown fox");
-    expect(newSide).toBe("the slow brown foxes");
-  });
-});
-
 describe("lcsDiff", () => {
   test("custom equality", () => {
     // Act
-    const ops = lcsDiff([{ v: 1 }, { v: 2 }], [{ v: 2 }, { v: 3 }], (oldItem, newItem) => oldItem.v === newItem.v);
+    const ops = lcsDiff(
+      [{ v: 1 }, { v: 2 }],
+      [{ v: 2 }, { v: 3 }],
+      (oldItem, newItem) => oldItem.v === newItem.v,
+    );
 
     // Assert
     expect(ops.map((op) => op.kind)).toEqual(["del", "ctx", "add"]);

package/src/diff.ts

@@ -22,12 +22,17 @@ export function lcsDiff<T>(
 ): DiffOp<T>[] {
   const oldCount = oldItems.length;
   const newCount = newItems.length;
-  const longestCommon: number[][] = Array.from({ length: oldCount + 1 }, () => new Array<number>(newCount + 1).fill(0));
+  const longestCommon: number[][] = Array.from({ length: oldCount + 1 }, () =>
+    Array.from({ length: newCount + 1 }, () => 0),
+  );
   for (let oldIndex = oldCount - 1; oldIndex >= 0; oldIndex--) {
     for (let newIndex = newCount - 1; newIndex >= 0; newIndex--) {
       longestCommon[oldIndex]![newIndex] = equals(oldItems[oldIndex]!, newItems[newIndex]!)
         ? longestCommon[oldIndex + 1]![newIndex + 1]! + 1
-        : Math.max(longestCommon[oldIndex + 1]![newIndex]!, longestCommon[oldIndex]![newIndex + 1]!);
+        : Math.max(
+            longestCommon[oldIndex + 1]![newIndex]!,
+            longestCommon[oldIndex]![newIndex + 1]!,
+          );
     }
   }
   const ops: DiffOp<T>[] = [];
@@ -76,7 +81,7 @@ export function unifiedDiff(oldText: string, newText: string, context = 3): Unif
     if (op.kind !== "del") newLineNumber++;
     return row;
   });
-  const keep = new Array<boolean>(rows.length).fill(false);
+  const keep = Array.from({ length: rows.length }, () => false);
   rows.forEach((row, rowIndex) => {
     if (row.kind !== "ctx") {
       for (
@@ -109,14 +114,22 @@ export function unifiedDiff(oldText: string, newText: string, context = 3): Unif
     const newCount = hunk.rows.filter((row) => row.kind !== "del").length;
     lines.push({ kind: "hunk", text: `@@ -${oldStart},${oldCount} +${newStart},${newCount} @@` });
     for (const row of hunk.rows) {
-      lines.push({ kind: row.kind, text: (row.kind === "add" ? "+" : row.kind === "del" ? "-" : " ") + row.text });
+      lines.push({
+        kind: row.kind,
+        text: (row.kind === "add" ? "+" : row.kind === "del" ? "-" : " ") + row.text,
+      });
     }
   }
   return lines;
 }
 
 /** Render a unified diff as text with file headers. */
-export function unifiedDiffText(oldText: string, newText: string, path = "plan.md", context = 3): string | null {
+export function unifiedDiffText(
+  oldText: string,
+  newText: string,
+  path = "plan.md",
+  context = 3,
+): string | null {
   const lines = unifiedDiff(oldText, newText, context);
   if (!lines) return null;
   return [`--- a/${path}`, `+++ b/${path}`, ...lines.map((line) => line.text)].join("\n");
@@ -135,9 +148,3 @@ export function editStats(oldText: string, newText: string): EditStats {
     removed: lines.filter((line) => line.kind === "del").length,
   };
 }
-
-/** Word-level diff ops for tracked-changes rendering. Whitespace-preserving. */
-export function wordDiff(oldText: string, newText: string): DiffOp[] {
-  const tokenize = (text: string) => text.split(/(\s+)/).filter((token) => token !== "");
-  return lcsDiff(tokenize(oldText), tokenize(newText));
-}

package/src/feedback.test.ts

@@ -13,7 +13,9 @@ Review sessions live only in daemon memory today.
 Sessions are written as one JSON document per session.
 `;
 
-function makeAnnotation(partial: Partial<Annotation> & { anchor: Annotation["anchor"] }): Annotation {
+function makeAnnotation(
+  partial: Partial<Annotation> & { anchor: Annotation["anchor"] },
+): Annotation {
   return {
     id: "a1",
     kind: "comment",
@@ -45,45 +47,73 @@ describe("renderFeedback", () => {
     expect(feedback).toContain("+Sessions are written as one JSON record per session.");
   });
 
-  test("annotations are located by quote and section", () => {
+  test("a diff working copy is handed back as the curated patch, not a diff of diffs", () => {
+    // Arrange
+    const submittedPatch = `--- a/src/x.ts
++++ b/src/x.ts
+@@ -1,1 +1,1 @@
+-const limit = 100;
++const limit = 250;
+`;
+    const curatedPatch = `--- a/src/x.ts
++++ b/src/x.ts
+@@ -1,1 +1,1 @@
+-const limit = 100;
++const limit = 175;
+`;
+
     // Act
     const feedback = renderFeedback({
-      verdictKind: "comment",
+      verdictKind: "request_changes",
       summary: "",
-      artifactContent: PLAN,
-      annotations: [
-        makeAnnotation({
-          anchor: { quote: "daemon memory", prefix: "live only in ", suffix: " today." },
-        }),
-      ],
+      artifactContent: submittedPatch,
+      workingCopy: curatedPatch,
+      artifactType: "diff",
+      annotations: [],
     });
 
     // Assert
-    expect(feedback).toContain("## Annotations (1)");
-    expect(feedback).toContain("### 1. Comment (§ Context)");
-    expect(feedback).toContain("> daemon memory");
-    expect(feedback).toContain("Please clarify.");
+    expect(feedback).toContain("## Curated changes");
+    expect(feedback).toContain("+const limit = 175;");
+    // the submitted patch is not re-diffed against the curated one
+    expect(feedback).not.toContain("Plan edits");
+    expect(feedback).not.toContain("++const");
   });
 
-  test("suggestions render as replace/with pairs", () => {
+  test("a diff working copy that rejected everything says so", () => {
     // Act
     const feedback = renderFeedback({
       verdictKind: "request_changes",
       summary: "",
+      artifactContent: "--- a/x\n+++ b/x\n@@ -1 +1 @@\n-a\n+b\n",
+      workingCopy: "",
+      artifactType: "diff",
+      annotations: [],
+    });
+
+    // Assert
+    expect(feedback).toContain("## Curated changes");
+    expect(feedback).toContain("rejected all of your proposed changes");
+  });
+
+  test("annotations are located by quote and section", () => {
+    // Act
+    const feedback = renderFeedback({
+      verdictKind: "comment",
+      summary: "",
       artifactContent: PLAN,
       annotations: [
         makeAnnotation({
-          kind: "suggestion",
-          body: "one durable JSON record",
-          anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." },
+          anchor: { quote: "daemon memory", prefix: "live only in ", suffix: " today." },
         }),
       ],
     });
 
     // Assert
-    expect(feedback).toContain("### 1. Suggested change (§ Storage)");
-    expect(feedback).toContain("Replace:\n> one JSON document");
-    expect(feedback).toContain("With:\n> one durable JSON record");
+    expect(feedback).toContain("## Annotations (1)");
+    expect(feedback).toContain("### 1. Comment (§ Context)");
+    expect(feedback).toContain("> daemon memory");
+    expect(feedback).toContain("Please clarify.");
   });
 
   test("orphaned anchors are flagged, never dropped", () => {
@@ -92,7 +122,9 @@ describe("renderFeedback", () => {
       verdictKind: "comment",
       summary: "",
       artifactContent: PLAN,
-      annotations: [makeAnnotation({ anchor: { quote: "text that is gone", prefix: "", suffix: "" } })],
+      annotations: [
+        makeAnnotation({ anchor: { quote: "text that is gone", prefix: "", suffix: "" } }),
+      ],
     });
 
     // Assert
@@ -122,7 +154,12 @@ describe("renderFeedback", () => {
     });
 
     // Act
-    const noteOnly = renderFeedback({ verdictKind: "approve", summary: "", artifactContent: PLAN, annotations: [note] });
+    const noteOnly = renderFeedback({
+      verdictKind: "approve",
+      summary: "",
+      artifactContent: PLAN,
+      annotations: [note],
+    });
 
     // Assert
     expect(noteOnly).toContain("_No edits or annotations._");
@@ -131,7 +168,12 @@ describe("renderFeedback", () => {
       verdictKind: "request_changes",
       summary: "",
       artifactContent: PLAN,
-      annotations: [note, makeAnnotation({ anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." } })],
+      annotations: [
+        note,
+        makeAnnotation({
+          anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." },
+        }),
+      ],
     });
     expect(mixed).toContain("## Annotations (1)");
     expect(mixed).not.toContain("The agent's own explanation of the change.");
@@ -149,7 +191,9 @@ describe("renderFeedback", () => {
       artifactContent: PLAN,
       workingCopy: working,
       annotations: [
-        makeAnnotation({ anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." } }),
+        makeAnnotation({
+          anchor: { quote: "one JSON document", prefix: "written as ", suffix: " per session." },
+        }),
       ],
     });
 

package/src/feedback.ts

@@ -5,7 +5,14 @@
  * by quoted text.
  */
 
-import { isAddressed, isAgentNote, type Annotation, type ReviewSession, type VerdictKind } from "./types";
+import {
+  isAddressed,
+  isAgentNote,
+  type Annotation,
+  type ArtifactType,
+  type ReviewSession,
+  type VerdictKind,
+} from "./types";
 import { parseBlocks, sectionOf } from "./markdown";
 import { resolveAnchor } from "./anchor";
 import { unifiedDiffText } from "./diff";
@@ -15,8 +22,11 @@ export interface FeedbackInput {
   summary: string;
   /** The submitted artifact content (latest revision). */
   artifactContent: string;
-  /** The reviewer's working copy; undefined = no direct edits. */
+  /** The reviewer's working copy; undefined = no direct edits. For a diff it is
+   *  the curated patch (accepted hunks); for a plan it is the edited source. */
   workingCopy?: string;
+  /** Artifact kind; defaults to "plan". A diff working copy is already a patch. */
+  artifactType?: ArtifactType;
   annotations: Annotation[];
   /** Path the agent knows the plan by, for direct reference. */
   planPath?: string;
@@ -31,8 +41,15 @@ export function renderFeedback(input: FeedbackInput): string {
   // agent notes are the submitter's own context - never echoed back as
   // feedback - and annotations a previous revision already addressed stay out
   // of the next document, so the agent only ever sees the open items
-  const annotations = input.annotations.filter((annotation) => !isAgentNote(annotation) && !isAddressed(annotation));
-  const blocks = parseBlocks(input.workingCopy ?? input.artifactContent);
+  const annotations = input.annotations.filter(
+    (annotation) => !isAgentNote(annotation) && !isAddressed(annotation),
+  );
+  const isDiff = input.artifactType === "diff";
+  // A diff's annotations anchor to the submitted patch rows; resolve against it,
+  // not the curated working copy (which may drop the rejected rows).
+  const blocks = parseBlocks(
+    isDiff ? input.artifactContent : (input.workingCopy ?? input.artifactContent),
+  );
   const lines: string[] = [];
   lines.push("# Review: " + input.verdictKind.replace("_", " "));
   lines.push("");
@@ -41,18 +58,41 @@ export function renderFeedback(input: FeedbackInput): string {
     lines.push("");
   }
 
-  const diff =
-    input.workingCopy !== undefined ? unifiedDiffText(input.artifactContent, input.workingCopy, path) : null;
-  if (diff) {
-    lines.push("## Plan edits");
+  let hasEdits = false;
+  if (isDiff && input.workingCopy !== undefined) {
+    // The diff working copy is already the curated patch - the accepted subset
+    // of the submitted changes - so hand it back verbatim, not a diff of diffs.
+    hasEdits = true;
+    lines.push("## Curated changes");
     lines.push("");
-    lines.push(`The reviewer edited ${path} directly. Apply this exact diff first;`);
-    lines.push("it is a unified diff against the version you submitted.");
-    lines.push("");
-    lines.push("```diff");
-    lines.push(diff);
-    lines.push("```");
+    if (input.workingCopy.trim()) {
+      lines.push("The reviewer accepted a subset of your proposed changes. Apply this");
+      lines.push("exact unified diff; it replaces what you submitted.");
+      lines.push("");
+      lines.push("```diff");
+      lines.push(input.workingCopy);
+      lines.push("```");
+    } else {
+      lines.push("The reviewer rejected all of your proposed changes.");
+    }
     lines.push("");
+  } else {
+    const diff =
+      input.workingCopy !== undefined
+        ? unifiedDiffText(input.artifactContent, input.workingCopy, path)
+        : null;
+    if (diff) {
+      hasEdits = true;
+      lines.push("## Plan edits");
+      lines.push("");
+      lines.push(`The reviewer edited ${path} directly. Apply this exact diff first;`);
+      lines.push("it is a unified diff against the version you submitted.");
+      lines.push("");
+      lines.push("```diff");
+      lines.push(diff);
+      lines.push("```");
+      lines.push("");
+    }
   }
 
   if (annotations.length) {
@@ -64,21 +104,15 @@ export function renderFeedback(input: FeedbackInput): string {
       const resolved = resolveAnchor(annotation.anchor, blocks);
       const sectionTitle = resolved ? sectionOf(blocks, resolved.blockIndex) : "";
       const location = sectionTitle ? ` (§ ${sectionTitle})` : "";
-      const orphanFlag = resolved === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
-      if (annotation.kind === "suggestion") {
-        lines.push(`### ${annotationIndex + 1}. Suggested change${location}${orphanFlag}`);
-        lines.push("");
-        lines.push("Replace:");
-        lines.push(quoteLines(annotation.anchor.quote));
-        lines.push("With:");
-        lines.push(quoteLines(annotation.body));
-      } else {
-        lines.push(`### ${annotationIndex + 1}. ${capitalize(annotation.kind)}${location}${orphanFlag}`);
-        lines.push("");
-        lines.push(quoteLines(annotation.anchor.quote));
-        lines.push("");
-        lines.push(annotation.body);
-      }
+      const orphanFlag =
+        resolved === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
+      lines.push(
+        `### ${annotationIndex + 1}. ${capitalize(annotation.kind)}${location}${orphanFlag}`,
+      );
+      lines.push("");
+      lines.push(quoteLines(annotation.anchor.quote));
+      lines.push("");
+      lines.push(annotation.body);
       lines.push("");
       lines.push(`annotation id: \`${annotation.id}\``);
       lines.push("");
@@ -90,25 +124,32 @@ export function renderFeedback(input: FeedbackInput): string {
       lines.push("they are marked addressed for the reviewer and leave the open list:");
       lines.push("");
       lines.push("```sh");
-      lines.push(`cueloop session submit-revision ${input.sessionId} --content-file ${path} --addressed <id,id,...>`);
+      lines.push(
+        `cueloop session submit-revision ${input.sessionId} --content-file ${path} --addressed <id,id,...>`,
+      );
       lines.push("```");
       lines.push("");
     }
   }
 
-  if (!diff && !annotations.length) {
+  if (!hasEdits && !annotations.length) {
     lines.push("_No edits or annotations._");
     lines.push("");
   }
   return lines.join("\n");
 }
 
-export function feedbackForSession(session: ReviewSession, verdictKind: VerdictKind, summary: string): string {
+export function feedbackForSession(
+  session: ReviewSession,
+  verdictKind: VerdictKind,
+  summary: string,
+): string {
   return renderFeedback({
     verdictKind,
     summary,
     artifactContent: session.artifact.content,
     workingCopy: session.workingCopy,
+    artifactType: session.artifact.type,
     annotations: session.annotations,
     planPath: session.artifact.meta.planPath,
     sessionId: session.id,

package/src/herdr.test.ts

@@ -4,8 +4,18 @@ import { detectHerdr, insideHerdr, returnPaneFor } from "./herdr";
 describe("detectHerdr", () => {
   test("null outside herdr, context inside", () => {
     expect(detectHerdr({})).toBeNull();
-    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1" })).toBeNull();
-    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1", HERDR_BIN_PATH: "/x/herdr" })).toEqual({
+    // no HERDR_ENV or no pane id means we are not in a usable herdr pane
+    expect(detectHerdr({ HERDR_PANE_ID: "p1" })).toBeNull();
+    expect(detectHerdr({ HERDR_ENV: "1" })).toBeNull();
+    // herdr 0.8.0 sets no HERDR_BIN_PATH: the binary defaults to `herdr` on PATH
+    expect(detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1" })).toEqual({
+      paneId: "p1",
+      binPath: "herdr",
+    });
+    // an explicit HERDR_BIN_PATH (tests, or a pinned install) still wins
+    expect(
+      detectHerdr({ HERDR_ENV: "1", HERDR_PANE_ID: "p1", HERDR_BIN_PATH: "/x/herdr" }),
+    ).toEqual({
       paneId: "p1",
       binPath: "/x/herdr",
     });

package/src/herdr.ts

@@ -1,10 +1,12 @@
 /**
  * The herdr ambient env contract, single-sourced. A process running inside a
- * herdr pane sees HERDR_ENV=1 plus the pane id and the herdr binary path.
- * Both the agent-side reporter (adapters) and the reviewer-side return-focus
- * (client) read this contract; decoding it in one place stops the two sides
- * drifting on which vars are required. Pure: no IO, env is only the default
- * argument so callers can pass a fixture.
+ * herdr pane sees HERDR_ENV=1 plus the pane id; the herdr CLI itself reaches
+ * the app over HERDR_SOCKET_PATH (which the spawned `herdr` reads from the
+ * inherited env), so the binary is just `herdr` on PATH. Both the agent-side
+ * reporter (adapters) and the reviewer-side return-focus (client) read this
+ * contract; decoding it in one place stops the two sides drifting on which
+ * vars are required. Pure: no IO, env is only the default argument so callers
+ * can pass a fixture.
  */
 
 export interface HerdrContext {
@@ -21,8 +23,11 @@ export type HerdrEnv = Record<string, string | undefined>;
 export function detectHerdr(env: HerdrEnv = process.env): HerdrContext | null {
   if (env.HERDR_ENV !== "1") return null;
   const paneId = env.HERDR_PANE_ID;
-  const binPath = env.HERDR_BIN_PATH;
-  if (!paneId || !binPath) return null;
+  if (!paneId) return null;
+  // herdr 0.8.0 exposes no HERDR_BIN_PATH; the CLI is `herdr` on PATH and finds
+  // the app over HERDR_SOCKET_PATH from the inherited env. Tests still override
+  // HERDR_BIN_PATH to point the spawn at a stub script.
+  const binPath = env.HERDR_BIN_PATH ?? "herdr";
   return { paneId, binPath };
 }
 
@@ -36,7 +41,10 @@ export function insideHerdr(env: HerdrEnv = process.env): boolean {
  * CUELOOP_RETURN_PANE, or the session's recorded pane, but never this pane
  * itself. Undefined outside herdr or when the only candidate is our own pane.
  */
-export function returnPaneFor(sessionHerdrPane?: string, env: HerdrEnv = process.env): string | undefined {
+export function returnPaneFor(
+  sessionHerdrPane?: string,
+  env: HerdrEnv = process.env,
+): string | undefined {
   if (!insideHerdr(env)) return undefined;
   const pane = env.CUELOOP_RETURN_PANE ?? sessionHerdrPane;
   return pane && pane !== env.HERDR_PANE_ID ? pane : undefined;

package/src/markdown.test.ts

@@ -93,7 +93,9 @@ describe("parseBlocks", () => {
     const again = parseBlocks(rebuilt);
 
     // Assert
-    expect(again.map((block) => [block.kind, block.text])).toEqual(blocks.map((block) => [block.kind, block.text]));
+    expect(again.map((block) => [block.kind, block.text])).toEqual(
+      blocks.map((block) => [block.kind, block.text]),
+    );
   });
 
   test("unknown constructs degrade to paragraphs, no content lost", () => {

package/src/markdown.ts

@@ -26,7 +26,7 @@ function isMarkerLine(line: string): boolean {
     line.startsWith("## ") ||
     line.startsWith("### ") ||
     line.startsWith("> ") ||
-    /^- /.test(line) ||
+    line.startsWith("- ") ||
     /^\d+\. /.test(line) ||
     /^(---|\*\*\*|___)\s*$/.test(line)
   );
@@ -73,17 +73,31 @@ export function parseBlocks(markdown: string): Block[] {
         body.push(lines[lineIndex]!.slice(2));
         lineIndex++;
       }
-      blocks.push({ kind: "quote", text: body.join("\n"), lineStart: start, lineEnd: lineIndex - 1 });
-    } else if (/^- /.test(line)) {
+      blocks.push({
+        kind: "quote",
+        text: body.join("\n"),
+        lineStart: start,
+        lineEnd: lineIndex - 1,
+      });
+    } else if (line.startsWith("- ")) {
       blocks.push({ kind: "li", text: line.slice(2), lineStart: lineIndex, lineEnd: lineIndex });
       lineIndex++;
     } else if (/^\d+\. /.test(line)) {
-      blocks.push({ kind: "oli", text: line.replace(/^\d+\. /, ""), lineStart: lineIndex, lineEnd: lineIndex });
+      blocks.push({
+        kind: "oli",
+        text: line.replace(/^\d+\. /, ""),
+        lineStart: lineIndex,
+        lineEnd: lineIndex,
+      });
       lineIndex++;
     } else {
       const start = lineIndex;
       const body: string[] = [];
-      while (lineIndex < lines.length && lines[lineIndex]!.trim() !== "" && !isMarkerLine(lines[lineIndex]!)) {
+      while (
+        lineIndex < lines.length &&
+        lines[lineIndex]!.trim() !== "" &&
+        !isMarkerLine(lines[lineIndex]!)
+      ) {
         body.push(lines[lineIndex]!);
         lineIndex++;
       }
@@ -125,7 +139,8 @@ export function sectionOf(blocks: Block[], index: number): string {
   let sectionTitle = "";
   for (let blockIndex = 0; blockIndex <= index && blockIndex < blocks.length; blockIndex++) {
     const block = blocks[blockIndex]!;
-    if (block.kind === "h1" || block.kind === "h2" || block.kind === "h3") sectionTitle = block.text;
+    if (block.kind === "h1" || block.kind === "h2" || block.kind === "h3")
+      sectionTitle = block.text;
   }
   return sectionTitle;
 }

package/src/types.ts

@@ -28,11 +28,29 @@ export interface ArtifactMeta {
   title?: string;
 }
 
+/** Full old/new contents of one changed file, keyed by its repo-relative path. */
+/** How a file changed, so curation emits the right create/delete headers. */
+export type DiffFileStatus = "added" | "modified" | "deleted";
+
+export interface DiffFileContents {
+  path: string;
+  oldContents: string;
+  newContents: string;
+  /** git's own classification - not inferred from empty contents, so an
+   *  existing-empty-file edit is a modify, not a create/delete. */
+  status: DiffFileStatus;
+}
+
 export interface Artifact {
   type: ArtifactType;
   /** Markdown source for plans; unified-diff text for diffs. */
   content: string;
   meta: ArtifactMeta;
+  /**
+   * Full file contents for a diff artifact, so hunk curation produces an
+   * exactly applyable patch; absent for legacy or partial (PR) diffs.
+   */
+  files?: DiffFileContents[];
 }
 
 /**
@@ -52,7 +70,7 @@ export interface Anchor {
 }
 
 /** The annotation kind set is open; these are the built-ins. */
-export type AnnotationKind = "comment" | "suggestion" | (string & {});
+export type AnnotationKind = "comment" | (string & {});
 
 /**
  * Agent-authored context, not reviewer feedback: the guided walk's per-file
@@ -68,7 +86,7 @@ export interface Annotation {
   id: string;
   kind: AnnotationKind;
   anchor: Anchor;
-  /** Comment body, or the replacement text for suggestions. */
+  /** Comment body. */
   body: string;
   /** Set by resolution when the quote can no longer be found. */
   orphan?: boolean;

package/src/working-copy.test.ts

@@ -25,11 +25,15 @@ function block(markdown: string, text: string): Block {
 describe("sourceChunk", () => {
   test("returns the exact source lines a block occupies", () => {
     expect(sourceChunk(BASE, block(BASE, "first item"))).toBe("- first item");
-    expect(sourceChunk(BASE, block(BASE, "spans two lines"))).toBe("A paragraph that\nspans two lines.");
+    expect(sourceChunk(BASE, block(BASE, "spans two lines"))).toBe(
+      "A paragraph that\nspans two lines.",
+    );
   });
 
   test("code block chunk includes both fence lines", () => {
-    expect(sourceChunk(BASE, block(BASE, "const x"))).toBe("```ts\nconst x = 1;\nconst y = 2;\n```");
+    expect(sourceChunk(BASE, block(BASE, "const x"))).toBe(
+      "```ts\nconst x = 1;\nconst y = 2;\n```",
+    );
   });
 });
 
@@ -84,7 +88,12 @@ describe("restoreBlock", () => {
     const next = parseBlocks(edited).find((candidate) => candidate.kind === "code");
 
     // Act
-    const restored = restoreBlock(BASE, edited, listItem, restoreLine(next, edited.split("\n").length));
+    const restored = restoreBlock(
+      BASE,
+      edited,
+      listItem,
+      restoreLine(next, edited.split("\n").length),
+    );
 
     // Assert
     expect(restored).toContain("- second item");
@@ -125,7 +134,9 @@ describe("restoreBlock", () => {
 
     // Assert
     // extra blank lines elsewhere do not block pristine detection
-    expect(restoreBlock(BASE, cut.replace("## Context", "## Context\n"), listItem, line)).toBeUndefined();
+    expect(
+      restoreBlock(BASE, cut.replace("## Context", "## Context\n"), listItem, line),
+    ).toBeUndefined();
     // a real text change keeps the working copy alive
     const changed = restoreBlock(BASE, cut.replace("first", "1st"), listItem, line);
     expect(changed).toContain("1st item");