@cueloop/schema 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/feedback.ts

@@ -1,12 +1,20 @@
 /**
  * feedback.md: the ONE structured markdown document the agent receives on
- * resolve (map #2, verified in the edit-mode deep-dive). Directive framing -
- * soft phrasing gets ignored by models: the plan diff is applied verbatim
- * first, then every annotation is addressed, located by quoted text.
+ * resolve. Directive framing - soft phrasing gets ignored by models: the plan
+ * diff is applied verbatim first, then every annotation is addressed, located
+ * by quoted text.
  */
 
-import type { Annotation, ReviewSession, VerdictKind } from "./types";
-import { parseBlocks, sectionOf } from "./markdown";
+import {
+  annotationTarget,
+  isAddressed,
+  isAgentNote,
+  type Annotation,
+  type ArtifactType,
+  type Thread,
+  type VerdictKind,
+} from "./types";
+import { parseBlocks, sectionOf, type Block } from "./markdown";
 import { resolveAnchor } from "./anchor";
 import { unifiedDiffText } from "./diff";
 
@@ -15,19 +23,63 @@ 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;
+  /** Path the agent knows the artifact by (plan or prototype), for direct reference. */
+  artifactPath?: string;
+  /** Session id, so the document can teach the addressed-ids resubmit call. */
+  sessionId?: string;
+  /** cueloop quick-action name -> body; a `/name` reference in a comment expands to it for the agent. */
+  actionBodies?: Record<string, string>;
 }
 
-const quoteLines = (s: string) => "> " + s.replace(/\n/g, "\n> ");
+const quoteLines = (text: string) => "> " + text.replace(/\n/g, "\n> ");
+
+function expandActionRefs(body: string, actionBodies: Record<string, string> | undefined): string {
+  if (!actionBodies) return body;
+
+  return body.replace(/(^|\s)\/([A-Za-z0-9-]+)/g, (whole, lead: string, name: string) =>
+    actionBodies[name] !== undefined ? `${lead}${actionBodies[name]}` : whole,
+  );
+}
 
 export function renderFeedback(input: FeedbackInput): string {
-  const path = input.planPath ?? "plan.md";
-  const blocks = parseBlocks(input.workingCopy ?? input.artifactContent);
+  // The document the agent revises: a reply's feedback references reply.md so
+  // the resubmit instruction never points a reply review at plan.md.
+  const path = input.artifactPath ?? (input.artifactType === "reply" ? "reply.md" : "plan.md");
+  // 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 open = input.annotations.filter(
+    (annotation) => !isAgentNote(annotation) && !isAddressed(annotation),
+  );
+  // a discussion is one item: the root comment, then its replies in order. A
+  // reply whose root was addressed leaves with it; only a reply whose root is
+  // gone entirely stands on its own
+  const openIds = new Set(open.map((annotation) => annotation.id));
+  const knownIds = new Set(input.annotations.map((annotation) => annotation.id));
+  const annotations = open.filter(
+    (annotation) =>
+      annotation.replyTo === undefined ||
+      (!openIds.has(annotation.replyTo) && !knownIds.has(annotation.replyTo)),
+  );
+  const repliesTo = (root: Annotation): Annotation[] =>
+    open
+      .filter((annotation) => annotation.replyTo === root.id)
+      .toSorted((left, right) => left.createdAt.localeCompare(right.createdAt));
+  const isDiff = input.artifactType === "diff";
+  const isPrototype = input.artifactType === "prototype";
+  // 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("");
   if (input.summary.trim()) {
@@ -35,66 +87,183 @@ 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.");
+    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("");
-    lines.push("```diff");
-    lines.push(diff);
-    lines.push("```");
+  } else {
+    const diff =
+      input.workingCopy !== undefined
+        ? unifiedDiffText(input.artifactContent, input.workingCopy, path)
+        : null;
+
+    if (diff) {
+      hasEdits = true;
+      // The edits section names the markdown artifact it edited (plan or reply)
+      // so the directive is not mislabelled when the artifact is not a plan.
+      lines.push(input.artifactType === "reply" ? "## Reply edits" : "## 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) {
+    lines.push(
+      ...annotationSectionLines(
+        annotations,
+        blocks,
+        path,
+        isPrototype,
+        repliesTo,
+        input.actionBodies,
+      ),
+    );
+    if (input.sessionId) {
+      lines.push("## Reporting what you addressed");
+      lines.push("");
+      lines.push("When you resubmit the revised plan, list the annotation ids you acted on -");
+      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("```");
+      lines.push("");
+    }
+  }
+
+  if (!hasEdits && !annotations.length) {
+    lines.push("_No edits or annotations._");
     lines.push("");
   }
 
-  if (input.annotations.length) {
-    lines.push(`## Annotations (${input.annotations.length})`);
+  return lines.join("\n");
+}
+
+/**
+ * The annotation body of the feedback, grouped by the surface each note was made on: the reviewed
+ * artifact first (resolved against its blocks for a section locator), then one section per file, so a
+ * note left on a file comes back beside that file rather than mixed into the plan's list.
+ */
+function annotationSectionLines(
+  annotations: Annotation[],
+  blocks: Block[],
+  path: string,
+  isPrototype: boolean,
+  repliesTo: (root: Annotation) => Annotation[],
+  actionBodies: Record<string, string> | undefined,
+): string[] {
+  const lines: string[] = [];
+  const artifactNotes = annotations.filter(
+    (annotation) => annotationTarget(annotation).kind === "artifact",
+  );
+  const fileGroups = new Map<string, Annotation[]>();
+
+  for (const annotation of annotations) {
+    const target = annotationTarget(annotation);
+
+    if (target.kind !== "file") continue;
+    const group = fileGroups.get(target.path) ?? [];
+
+    group.push(annotation);
+    fileGroups.set(target.path, group);
+  }
+
+  const pushNote = (annotation: Annotation, index: number, location: string, orphan: string) => {
+    lines.push(`### ${index + 1}. ${capitalize(annotation.kind)}${location}${orphan}`);
+    lines.push("");
+    lines.push(quoteLines(annotation.anchor.quote));
     lines.push("");
-    lines.push(`Address every item. Locate each one in ${path} by its quoted text.`);
+    lines.push(expandActionRefs(annotation.body, actionBodies));
     lines.push("");
-    input.annotations.forEach((a, i) => {
-      const res = resolveAnchor(a.anchor, blocks);
-      const sec = res ? sectionOf(blocks, res.blockIndex) : "";
-      const loc = sec ? ` (§ ${sec})` : "";
-      const flag = res === null ? " [orphaned anchor: the quoted text is no longer present]" : "";
-      if (a.kind === "suggestion") {
-        lines.push(`### ${i + 1}. Suggested change${loc}${flag}`);
-        lines.push("");
-        lines.push("Replace:");
-        lines.push(quoteLines(a.anchor.quote));
-        lines.push("With:");
-        lines.push(quoteLines(a.body));
-      } else {
-        lines.push(`### ${i + 1}. ${capitalize(a.kind)}${loc}${flag}`);
-        lines.push("");
-        lines.push(quoteLines(a.anchor.quote));
-        lines.push("");
-        lines.push(a.body);
-      }
+    const replies = repliesTo(annotation);
+
+    if (replies.length > 0) {
+      lines.push("Replies:");
+      lines.push("");
+      for (const reply of replies)
+        lines.push(`- ${expandActionRefs(reply.body, actionBodies).replace(/\n/g, "\n  ")}`);
       lines.push("");
+    }
+    lines.push(`annotation id: \`${annotation.id}\``);
+    lines.push("");
+  };
+
+  if (artifactNotes.length) {
+    lines.push(`## Annotations (${artifactNotes.length})`);
+    lines.push("");
+    lines.push(
+      isPrototype
+        ? `Address every item. Locate each one in ${path} by its CSS selector.`
+        : `Address every item. Locate each one in ${path} by its quoted text.`,
+    );
+    lines.push("");
+    artifactNotes.forEach((annotation, index) => {
+      // a prototype selector anchor never resolves or orphans against blocks; a quote anchor does
+      const selector = annotation.anchor.selector;
+      const resolved = selector ? null : resolveAnchor(annotation.anchor, blocks);
+      const sectionTitle = resolved ? sectionOf(blocks, resolved.blockIndex) : "";
+      const location = selector ? ` (${selector})` : sectionTitle ? ` (§ ${sectionTitle})` : "";
+      const orphan =
+        !selector && resolved === null
+          ? " [orphaned anchor: the quoted text is no longer present]"
+          : "";
+
+      pushNote(annotation, index, location, orphan);
     });
   }
-
-  if (!diff && !input.annotations.length) {
-    lines.push("_No edits or annotations._");
+  for (const [filePath, notes] of fileGroups) {
+    lines.push(`## ${filePath} (${notes.length})`);
+    lines.push("");
+    lines.push(`Address every item. Locate each one in ${filePath} by its quoted text.`);
     lines.push("");
+    notes.forEach((annotation, index) => pushNote(annotation, index, "", ""));
   }
-  return lines.join("\n");
+
+  return lines;
 }
 
-export function feedbackForSession(session: ReviewSession, verdictKind: VerdictKind, summary: string): string {
+export function feedbackForSession(
+  session: Thread,
+  verdictKind: VerdictKind,
+  summary: string,
+  actionBodies?: Record<string, 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,
+    artifactPath: session.artifact.meta.prototypePath ?? session.artifact.meta.planPath,
+    sessionId: session.id,
+    actionBodies,
   });
 }
 
-function capitalize(s: string): string {
-  return s.charAt(0).toUpperCase() + s.slice(1);
+function capitalize(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
 }

package/src/fuzzy.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import { fuzzyFindBestMatch, levenshteinDistance, similarityRatio } from "./fuzzy";
+
+describe("levenshteinDistance", () => {
+  test("identical strings cost nothing", () => {
+    // Arrange / Act / Assert
+    expect(levenshteinDistance("anchor", "anchor")).toBe(0);
+  });
+
+  test("counts a single substitution", () => {
+    // Arrange / Act / Assert
+    expect(levenshteinDistance("plan", "plane")).toBe(1);
+  });
+
+  test("empty against non-empty costs the whole length", () => {
+    // Arrange / Act / Assert
+    expect(levenshteinDistance("", "quote")).toBe(5);
+  });
+
+  test("is symmetric", () => {
+    // Arrange / Act / Assert
+    expect(levenshteinDistance("kitten", "sitting")).toBe(levenshteinDistance("sitting", "kitten"));
+  });
+});
+
+describe("similarityRatio", () => {
+  test("two empty strings are identical", () => {
+    // Arrange / Act / Assert
+    expect(similarityRatio("", "")).toBe(1);
+  });
+
+  test("identical strings score one", () => {
+    // Arrange / Act / Assert
+    expect(similarityRatio("review", "review")).toBe(1);
+  });
+
+  test("a one-character typo in a long string stays close to one", () => {
+    // Arrange
+    const original = "demonstration plan";
+
+    // Act
+    const ratio = similarityRatio(original, "demonstration plann");
+
+    // Assert
+    expect(ratio).toBeGreaterThan(0.9);
+  });
+
+  test("unrelated strings score low", () => {
+    // Arrange / Act / Assert
+    expect(similarityRatio("abcdef", "zyxwvu")).toBeLessThan(0.2);
+  });
+});
+
+describe("fuzzyFindBestMatch", () => {
+  test("finds a lightly edited window and reports its offsets", () => {
+    // Arrange
+    const haystack = "the quick brown fox jumps";
+
+    // Act
+    const match = fuzzyFindBestMatch("quikc brown", haystack, 0.75)!;
+
+    // Assert
+    expect(match).not.toBeNull();
+    expect(haystack.slice(match.start, match.end)).toBe("quick brown");
+    expect(match.similarity).toBeGreaterThan(0.75);
+  });
+
+  test("returns null when nothing clears the similarity floor", () => {
+    // Arrange / Act
+    const match = fuzzyFindBestMatch("completely unrelated", "short text", 0.75);
+
+    // Assert
+    expect(match).toBeNull();
+  });
+
+  test("an empty needle or haystack never matches", () => {
+    // Arrange / Act / Assert
+    expect(fuzzyFindBestMatch("", "text", 0.75)).toBeNull();
+    expect(fuzzyFindBestMatch("text", "", 0.75)).toBeNull();
+  });
+
+  test("ties keep the earliest window", () => {
+    // Arrange
+    const haystack = "word word";
+
+    // Act
+    const match = fuzzyFindBestMatch("word", haystack, 0.9)!;
+
+    // Assert
+    expect(match.start).toBe(0);
+  });
+
+  test("a long quote fuzzed over a long document bails within its work budget", () => {
+    // Arrange - a stale multi-line anchor whose text is gone, over a large document; the naive
+    // scan is O(haystack * needle^3) and would pin the CPU for a minute
+    const needle = Array.from({ length: 200 }, (_unused, index) => `token-${index}`).join(" ");
+    const haystack = Array.from(
+      { length: 400 },
+      (_unused, index) => `line ${index} of the diff`,
+    ).join("\n");
+
+    // Act
+    const started = Date.now();
+    const match = fuzzyFindBestMatch(needle, haystack, 0.75);
+
+    // Assert - it returns (here: no match clears the bar) fast, never spinning
+    expect(match).toBeNull();
+    expect(Date.now() - started).toBeLessThan(2000);
+  });
+});

package/src/fuzzy.ts

@@ -0,0 +1,115 @@
+/**
+ * Approximate string matching for anchor re-binding. The anchor resolver falls
+ * back to these when exact and marker-normalized quote lookups both miss - the
+ * quoted text is still present but was lightly edited (a word changed, a typo
+ * fixed, punctuation adjusted). Everything here is pure and offset-exact so it
+ * can be tested in isolation from the resolver.
+ */
+
+/** A window of the haystack that best matches the needle. */
+export interface FuzzyMatch {
+  /** Inclusive start offset into the haystack. */
+  start: number;
+  /** Exclusive end offset into the haystack. */
+  end: number;
+  /** Similarity of the matched window to the needle, in [0, 1]. */
+  similarity: number;
+}
+
+/**
+ * Levenshtein edit distance: the fewest single-character insertions, deletions,
+ * or substitutions that turn `left` into `right`. Uses two rolling rows, so it
+ * costs O(left.length * right.length) time and O(right.length) space.
+ */
+export function levenshteinDistance(left: string, right: string): number {
+  if (left === right) return 0;
+  if (left.length === 0) return right.length;
+  if (right.length === 0) return left.length;
+
+  let previousRow: number[] = Array.from({ length: right.length + 1 }, (_unused, column) => column);
+  let currentRow: number[] = Array.from({ length: right.length + 1 }, () => 0);
+
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex++) {
+    currentRow[0] = leftIndex;
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex++) {
+      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+
+      currentRow[rightIndex] = Math.min(
+        currentRow[rightIndex - 1]! + 1, // insertion
+        previousRow[rightIndex]! + 1, // deletion
+        previousRow[rightIndex - 1]! + substitutionCost, // substitution
+      );
+    }
+    const swap = previousRow;
+
+    previousRow = currentRow;
+    currentRow = swap;
+  }
+
+  return previousRow[right.length]!;
+}
+
+/**
+ * Similarity of two strings in [0, 1]: 1 is identical, 0 shares nothing. Derived
+ * from the edit distance normalized by the longer string. Two empty strings are
+ * defined as identical (1).
+ */
+export function similarityRatio(left: string, right: string): number {
+  const longestLength = Math.max(left.length, right.length);
+
+  if (longestLength === 0) return 1;
+
+  return 1 - levenshteinDistance(left, right) / longestLength;
+}
+
+/**
+ * Character comparisons this scan may spend before it gives up and returns the
+ * best window found so far (or null). The scan is O(haystack * needle^3) - a
+ * long quote fuzzed over a long document (a stale multi-block anchor whose text
+ * is gone) would otherwise pin the CPU for a minute; a passage that is truly gone
+ * is better left orphaned than fuzzed. Small everyday quotes never approach it.
+ */
+const FUZZY_WORK_BUDGET = 150_000_000;
+
+/**
+ * Find the haystack window most similar to the needle, or null when nothing
+ * clears `minimumSimilarity`. Windows range around the needle length so the
+ * match tolerates a few inserted or deleted characters, not only substitutions.
+ * Ties keep the earliest window. Offsets index the haystack directly. The scan
+ * stops once it has spent `FUZZY_WORK_BUDGET`, returning the best window so far.
+ */
+export function fuzzyFindBestMatch(
+  needle: string,
+  haystack: string,
+  minimumSimilarity: number,
+): FuzzyMatch | null {
+  if (needle === "" || haystack === "") return null;
+
+  const lengthTolerance = Math.max(2, Math.round(needle.length * 0.25));
+  const minimumWindowLength = Math.max(1, needle.length - lengthTolerance);
+  const maximumWindowLength = needle.length + lengthTolerance;
+
+  let bestMatch: FuzzyMatch | null = null;
+  let remainingWork = FUZZY_WORK_BUDGET;
+
+  for (let start = 0; start < haystack.length; start++) {
+    for (
+      let windowLength = minimumWindowLength;
+      windowLength <= maximumWindowLength && start + windowLength <= haystack.length;
+      windowLength++
+    ) {
+      // each window costs a needle x window edit-distance pass; spend that from the budget
+      remainingWork -= needle.length * windowLength;
+      if (remainingWork <= 0) return bestMatch;
+      const window = haystack.slice(start, start + windowLength);
+      const similarity = similarityRatio(needle, window);
+
+      if (similarity < minimumSimilarity) continue;
+      if (bestMatch === null || similarity > bestMatch.similarity) {
+        bestMatch = { start, end: start + windowLength, similarity };
+      }
+    }
+  }
+
+  return bestMatch;
+}

package/src/herdr.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { detectHerdr, insideHerdr, returnPaneFor } from "./herdr";
+
+describe("detectHerdr", () => {
+  test("null outside herdr, context inside", () => {
+    expect(detectHerdr({})).toBeNull();
+    // 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",
+    });
+  });
+});
+
+describe("insideHerdr", () => {
+  test("true only when HERDR_ENV is exactly 1", () => {
+    expect(insideHerdr({})).toBeFalse();
+    expect(insideHerdr({ HERDR_ENV: "0" })).toBeFalse();
+    expect(insideHerdr({ HERDR_ENV: "1" })).toBeTrue();
+  });
+});
+
+describe("returnPaneFor", () => {
+  test("outside herdr there is never a return target", () => {
+    expect(returnPaneFor("w1:p1", {})).toBeUndefined();
+  });
+
+  test("env override wins, session meta is the fallback", () => {
+    // Arrange
+    const inside = { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p9" };
+
+    // Assert
+    expect(returnPaneFor("w1:p1", inside)).toBe("w1:p1");
+    expect(returnPaneFor("w1:p1", { ...inside, CUELOOP_RETURN_PANE: "w1:p2" })).toBe("w1:p2");
+  });
+
+  test("returning to our own pane is a no-op", () => {
+    expect(returnPaneFor("w1:p1", { HERDR_ENV: "1", HERDR_PANE_ID: "w1:p1" })).toBeUndefined();
+  });
+});

package/src/herdr.ts

@@ -0,0 +1,54 @@
+/**
+ * The herdr ambient env contract, single-sourced. A process running inside a
+ * 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 {
+  paneId: string;
+  binPath: string;
+}
+
+export type HerdrEnv = Record<string, string | undefined>;
+
+/**
+ * The pane's full contract - pane id and binary path - or null outside a
+ * functioning herdr. Required by anything that spawns the herdr CLI.
+ */
+export function detectHerdr(env: HerdrEnv = process.env): HerdrContext | null {
+  if (env.HERDR_ENV !== "1") return null;
+  const paneId = env.HERDR_PANE_ID;
+
+  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 };
+}
+
+/** True whenever this process runs inside a herdr pane. */
+export function insideHerdr(env: HerdrEnv = process.env): boolean {
+  return env.HERDR_ENV === "1";
+}
+
+/**
+ * The pane a closing review should hand focus back to: the opener's
+ * 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 {
+  if (!insideHerdr(env)) return undefined;
+  const pane = env.CUELOOP_RETURN_PANE ?? sessionHerdrPane;
+
+  return pane && pane !== env.HERDR_PANE_ID ? pane : undefined;
+}