@cueloop/client 0.1.0-alpha.6 → 0.1.0-alpha.8

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@cueloop/daemon": "0.1.0-alpha.6",
-    "@cueloop/extension-api": "0.1.0-alpha.6",
-    "@cueloop/integration-obsidian": "0.1.0-alpha.6",
-    "@cueloop/schema": "0.1.0-alpha.6",
+    "@cueloop/daemon": "0.1.0-alpha.8",
+    "@cueloop/extension-api": "0.1.0-alpha.8",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.8",
+    "@cueloop/schema": "0.1.0-alpha.8",
     "@opentui/core": "^0.4.3",
     "@opentui/react": "^0.4.3",
     "@opentui/ssh": "0.4.5",

package/src/keymap.test.ts

@@ -0,0 +1,263 @@
+/**
+ * The keyboard grammar as data: every mode x key produces a known intent
+ * list, the read-only rule is one gate, and plan and diff reviews share one
+ * path for annotation navigation, deletion, and submit.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_KEYS } from "./config";
+import { reduceKey, type Intent, type KeyState } from "./keymap";
+
+function state(patch: Partial<KeyState> = {}): KeyState {
+  return {
+    keys: DEFAULT_KEYS,
+    readOnly: false,
+    overlay: "none",
+    view: "plan",
+    spanMode: false,
+    resolved: false,
+    hasInboxItems: true,
+    annotationCount: 1,
+    hasFocusedAnnotation: true,
+    cursorAnnotatable: true,
+    ...patch,
+  };
+}
+
+function key(name: string, shift = false): { name: string; shift: boolean } {
+  return { name, shift };
+}
+
+describe("compose overlay", () => {
+  const s = state({ overlay: "compose" });
+  const table: [string, Intent[]][] = [
+    ["escape", [{ t: "closeOverlay" }]],
+    ["return", [{ t: "saveCompose" }]],
+    ["enter", [{ t: "saveCompose" }]],
+    ["left", []],
+    ["right", []],
+    ["j", []],
+    ["q", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("submit overlay", () => {
+  const s = state({ overlay: "submit" });
+  const table: [string, Intent[]][] = [
+    ["escape", [{ t: "closeOverlay" }]],
+    ["return", [{ t: "submitVerdict" }]],
+    ["enter", [{ t: "submitVerdict" }]],
+    ["left", [{ t: "cycleVerdict", dir: -1 }]],
+    ["right", [{ t: "cycleVerdict", dir: 1 }]],
+    ["j", []],
+    ["q", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("completion overlay", () => {
+  const prompt = state({ overlay: "completion-prompt" });
+  const counting = state({ overlay: "completion-counting" });
+  const table: [KeyState, string, Intent[]][] = [
+    [prompt, "return", [{ t: "finishReview" }]],
+    [prompt, "enter", [{ t: "finishReview" }]],
+    [prompt, "q", [{ t: "finishReview" }]],
+    [prompt, "a", [{ t: "optInAutoClose" }]],
+    [prompt, "escape", [{ t: "dismissCompletion" }]],
+    [prompt, "j", []],
+    [counting, "return", [{ t: "finishReview" }]],
+    [counting, "q", [{ t: "finishReview" }]],
+    [counting, "a", []],
+    [counting, "escape", [{ t: "dismissCompletion" }]],
+  ];
+  for (const [s, name, expected] of table) {
+    test(`${s.overlay} ${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("inbox mode", () => {
+  const s = state({ view: "inbox" });
+  const table: [string, Intent[]][] = [
+    ["j", [{ t: "inboxMove", to: "down" }]],
+    ["down", [{ t: "inboxMove", to: "down" }]],
+    ["k", [{ t: "inboxMove", to: "up" }]],
+    ["up", [{ t: "inboxMove", to: "up" }]],
+    ["return", [{ t: "openSession" }]],
+    ["enter", [{ t: "openSession" }]],
+    ["q", [{ t: "exit" }]],
+    ["c", []],
+    ["escape", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+
+  test("an empty inbox swallows every non-quit key", () => {
+    const empty = state({ view: "inbox", hasInboxItems: false });
+    for (const name of ["j", "k", "down", "up", "return", "enter"]) {
+      expect(reduceKey(empty, key(name))).toEqual([]);
+    }
+    expect(reduceKey(empty, key("q"))).toEqual([{ t: "exit" }]);
+  });
+});
+
+describe("plan normal mode", () => {
+  const s = state();
+  const table: [string, boolean, Intent[]][] = [
+    ["j", false, [{ t: "move", to: "down" }]],
+    ["down", false, [{ t: "move", to: "down" }]],
+    ["k", false, [{ t: "move", to: "up" }]],
+    ["up", false, [{ t: "move", to: "up" }]],
+    ["g", false, [{ t: "move", to: "top" }]],
+    ["g", true, [{ t: "move", to: "bottom" }]],
+    ["v", false, [{ t: "startSpan" }]],
+    ["c", false, [{ t: "openCompose", kind: "comment", from: "cursor" }]],
+    ["s", false, [{ t: "openCompose", kind: "suggestion", from: "cursor" }]],
+    ["x", false, [{ t: "cut" }]],
+    ["e", false, [{ t: "edit" }]],
+    ["n", false, [{ t: "nextAnn" }]],
+    ["p", false, [{ t: "prevAnn" }]],
+    ["backspace", false, [{ t: "removeAnnotation" }]],
+    ["return", false, [{ t: "openSubmit" }]],
+    ["q", false, [{ t: "exit" }]],
+    ["escape", false, []],
+    ["z", false, []],
+  ];
+  for (const [name, shift, expected] of table) {
+    test(`${shift ? "shift+" : ""}${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name, shift))).toEqual(expected);
+    });
+  }
+
+  test("resolved sessions guard the mutating verbs", () => {
+    const r = state({ resolved: true });
+    for (const name of ["c", "s", "x", "e"]) {
+      expect(reduceKey(r, key(name))).toEqual([{ t: "status", msg: "review submitted - read-only" }]);
+    }
+    expect(reduceKey(r, key("return"))).toEqual([]);
+    expect(reduceKey(r, key("backspace"))).toEqual([]);
+  });
+
+  test("cut text cannot host a comment or a span", () => {
+    const cut = state({ cursorAnnotatable: false });
+    expect(reduceKey(cut, key("c"))).toEqual([{ t: "status", msg: "text is cut - restore it first" }]);
+    expect(reduceKey(cut, key("s"))).toEqual([{ t: "status", msg: "text is cut - restore it first" }]);
+    expect(reduceKey(cut, key("v"))).toEqual([]);
+  });
+
+  test("annotation navigation without annotations reports, delete without focus is silent", () => {
+    const none = state({ annotationCount: 0, hasFocusedAnnotation: false });
+    expect(reduceKey(none, key("n"))).toEqual([{ t: "status", msg: "no annotations" }]);
+    expect(reduceKey(none, key("p"))).toEqual([{ t: "status", msg: "no annotations" }]);
+    expect(reduceKey(none, key("backspace"))).toEqual([]);
+  });
+});
+
+describe("span mode", () => {
+  const s = state({ spanMode: true });
+  const table: [string, Intent[]][] = [
+    ["l", [{ t: "spanKey", name: "l" }]],
+    ["h", [{ t: "spanKey", name: "h" }]],
+    ["w", [{ t: "spanKey", name: "w" }]],
+    ["b", [{ t: "spanKey", name: "b" }]],
+    ["$", [{ t: "spanKey", name: "$" }]],
+    ["0", [{ t: "spanKey", name: "0" }]],
+    ["c", [{ t: "openCompose", kind: "comment", from: "span" }]],
+    ["s", [{ t: "openCompose", kind: "suggestion", from: "span" }]],
+    ["escape", [{ t: "closeOverlay" }]],
+    ["q", [{ t: "exit" }]],
+    ["j", []],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+});
+
+describe("diff mode", () => {
+  const s = state({ view: "diff" });
+  const table: [string, Intent[]][] = [
+    ["j", [{ t: "move", to: "down" }]],
+    ["k", [{ t: "move", to: "up" }]],
+    ["g", [{ t: "move", to: "top" }]],
+    ["c", [{ t: "openCompose", kind: "comment", from: "cursor" }]],
+    ["n", [{ t: "nextAnn" }]],
+    ["p", [{ t: "prevAnn" }]],
+    ["backspace", [{ t: "removeAnnotation" }]],
+    ["return", [{ t: "openSubmit" }]],
+    ["v", [{ t: "status", msg: "plan-only verb - diff review uses c on a line" }]],
+    ["x", [{ t: "status", msg: "plan-only verb - diff review uses c on a line" }]],
+    ["e", [{ t: "status", msg: "plan-only verb - diff review uses c on a line" }]],
+    ["s", [{ t: "status", msg: "plan-only verb - diff review uses c on a line" }]],
+    ["q", [{ t: "exit" }]],
+  ];
+  for (const [name, expected] of table) {
+    test(`${name} -> ${JSON.stringify(expected)}`, () => {
+      expect(reduceKey(s, key(name))).toEqual(expected);
+    });
+  }
+
+  test("comment guards: resolved first, then non-code rows", () => {
+    expect(reduceKey(state({ view: "diff", resolved: true }), key("c"))).toEqual([
+      { t: "status", msg: "review submitted - read-only" },
+    ]);
+    expect(reduceKey(state({ view: "diff", cursorAnnotatable: false }), key("c"))).toEqual([
+      { t: "status", msg: "move to a code line to comment" },
+    ]);
+  });
+});
+
+describe("duplicated-branch collapse", () => {
+  test("plan and diff produce the same intents for annotation nav, delete, and submit", () => {
+    for (const patch of [
+      {},
+      { annotationCount: 0, hasFocusedAnnotation: false },
+      { resolved: true },
+    ] as Partial<KeyState>[]) {
+      for (const name of ["n", "p", "backspace", "return"]) {
+        const plan = reduceKey(state(patch), key(name));
+        const diff = reduceKey(state({ ...patch, view: "diff" }), key(name));
+        expect(diff).toEqual(plan);
+      }
+    }
+  });
+});
+
+describe("read-only filter", () => {
+  test("every mutating key answers observer - read-only, in plan and diff", () => {
+    for (const view of ["plan", "diff"] as const) {
+      const s = state({ view, readOnly: true });
+      for (const name of ["c", "s", "x", "e", "backspace", "return", "enter"]) {
+        expect(reduceKey(s, key(name))).toEqual([{ t: "status", msg: "observer - read-only" }]);
+      }
+    }
+  });
+
+  test("navigation and annotation focus still work for observers", () => {
+    const s = state({ readOnly: true });
+    expect(reduceKey(s, key("j"))).toEqual([{ t: "move", to: "down" }]);
+    expect(reduceKey(s, key("n"))).toEqual([{ t: "nextAnn" }]);
+    expect(reduceKey(s, key("q"))).toEqual([{ t: "exit" }]);
+  });
+
+  test("span-mode c/s are gated by key name even under a rebound keymap", () => {
+    const rebound = { ...DEFAULT_KEYS, comment: ["m"], suggest: ["t"] };
+    const s = state({ spanMode: true, readOnly: true, keys: rebound });
+    expect(reduceKey(s, key("c"))).toEqual([{ t: "status", msg: "observer - read-only" }]);
+    expect(reduceKey(s, key("s"))).toEqual([{ t: "status", msg: "observer - read-only" }]);
+  });
+});

package/src/keymap.ts

@@ -0,0 +1,167 @@
+/**
+ * The keyboard grammar as a pure reducer (#70): view state in, intents out.
+ * App builds a KeyState per key event, calls reduceKey, and dispatches the
+ * intents to controller verbs and view-state setters - no branch bodies live
+ * in the key handler. Diff and plan reviews share one path for annotation
+ * navigation, deletion, and submit; the read-only rule is one gate here.
+ */
+
+import { actionFor } from "./config";
+
+export type Intent =
+  | { t: "exit" }
+  | { t: "status"; msg: string }
+  | { t: "move"; to: "down" | "up" | "top" | "bottom" }
+  | { t: "inboxMove"; to: "down" | "up" }
+  | { t: "openSession" }
+  | { t: "startSpan" }
+  | { t: "spanKey"; name: string }
+  | { t: "openCompose"; kind: "comment" | "suggestion"; from: "cursor" | "span" }
+  | { t: "openSubmit" }
+  | { t: "cut" }
+  | { t: "edit" }
+  | { t: "nextAnn" }
+  | { t: "prevAnn" }
+  | { t: "removeAnnotation" }
+  | { t: "closeOverlay" }
+  | { t: "saveCompose" }
+  | { t: "submitVerdict" }
+  | { t: "cycleVerdict"; dir: -1 | 1 }
+  | { t: "finishReview" }
+  | { t: "optInAutoClose" }
+  | { t: "dismissCompletion" };
+
+export interface KeyInput {
+  name: string;
+  shift: boolean;
+}
+
+export interface KeyState {
+  /** Loaded keymap (config.ts): action -> key combos. */
+  keys: Record<string, string[]>;
+  readOnly: boolean;
+  /** Layer that owns keys before the grammar runs. */
+  overlay: "none" | "compose" | "submit" | "completion-prompt" | "completion-counting";
+  view: "inbox" | "plan" | "diff";
+  /** Plan-only span selection sub-mode. */
+  spanMode: boolean;
+  resolved: boolean;
+  hasInboxItems: boolean;
+  annotationCount: number;
+  hasFocusedAnnotation: boolean;
+  /** Cursor sits on annotatable text: a work block (plan) or a code row (diff). */
+  cursorAnnotatable: boolean;
+}
+
+/** Verbs that write session state; an observer never reaches their handlers. */
+const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit"]);
+
+const SPAN_KEYS = ["l", "h", "w", "b", "$", "0"];
+
+function status(msg: string): Intent[] {
+  return [{ t: "status", msg }];
+}
+
+export function reduceKey(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+  // compose/submit overlays own the keys via focused inputs; only escape,
+  // return, and verdict arrows route through the grammar
+  if (state.overlay === "compose" || state.overlay === "submit") {
+    if (name === "escape") return [{ t: "closeOverlay" }];
+    if (name === "return" || name === "enter") {
+      return [state.overlay === "compose" ? { t: "saveCompose" } : { t: "submitVerdict" }];
+    }
+    if (state.overlay === "submit" && (name === "left" || name === "right")) {
+      return [{ t: "cycleVerdict", dir: name === "left" ? -1 : 1 }];
+    }
+    return [];
+  }
+  if (state.overlay === "completion-prompt" || state.overlay === "completion-counting") {
+    if (name === "return" || name === "enter" || name === "q") return [{ t: "finishReview" }];
+    if (name === "a" && state.overlay === "completion-prompt") return [{ t: "optInAutoClose" }];
+    if (name === "escape") return [{ t: "dismissCompletion" }];
+    return [];
+  }
+  const action = actionFor(state.keys, name, key.shift);
+  if (action === "quit") return [{ t: "exit" }];
+  // the ONE read-only rule: any mutating attempt answers instead of acting
+  // (span-mode c/s are hardwired keys, so they gate by name as well)
+  const mutating = MUTATING_ACTIONS.has(action ?? "") || (state.spanMode && (name === "c" || name === "s"));
+  if (state.readOnly && mutating) return status("observer - read-only");
+
+  if (state.view === "inbox") return inboxGrammar(state, name);
+  if (state.view === "diff") return diffGrammar(state, action);
+  if (state.spanMode) return spanGrammar(name);
+  return planGrammar(state, action);
+}
+
+function inboxGrammar(state: KeyState, name: string): Intent[] {
+  if (!state.hasInboxItems) return [];
+  if (name === "j" || name === "down") return [{ t: "inboxMove", to: "down" }];
+  if (name === "k" || name === "up") return [{ t: "inboxMove", to: "up" }];
+  if (name === "return" || name === "enter") return [{ t: "openSession" }];
+  return [];
+}
+
+function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
+  const nav = navIntent(action);
+  if (nav) return nav;
+  if (action === "comment") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (!state.cursorAnnotatable) return status("move to a code line to comment");
+    return [{ t: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  const shared = annotationCluster(state, action);
+  if (shared) return shared;
+  if (action === "span" || action === "cut" || action === "edit" || action === "suggest") {
+    return status("plan-only verb - diff review uses c on a line");
+  }
+  return [];
+}
+
+function spanGrammar(name: string): Intent[] {
+  if (name === "escape") return [{ t: "closeOverlay" }];
+  if (SPAN_KEYS.includes(name)) return [{ t: "spanKey", name }];
+  if (name === "c" || name === "s") {
+    return [{ t: "openCompose", kind: name === "s" ? "suggestion" : "comment", from: "span" }];
+  }
+  return [];
+}
+
+function planGrammar(state: KeyState, action: string | undefined): Intent[] {
+  const nav = navIntent(action);
+  if (nav) return nav;
+  if (action === "span") return state.cursorAnnotatable ? [{ t: "startSpan" }] : [];
+  if (action === "comment" || action === "suggest") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (!state.cursorAnnotatable) return status("text is cut - restore it first");
+    return [{ t: "openCompose", kind: action === "suggest" ? "suggestion" : "comment", from: "cursor" }];
+  }
+  if (action === "cut" || action === "edit") {
+    if (state.resolved) return status("review submitted - read-only");
+    return [{ t: action }];
+  }
+  return annotationCluster(state, action) ?? [];
+}
+
+/** Cursor movement is the same intent everywhere; views clamp their own bounds. */
+function navIntent(action: string | undefined): Intent[] | null {
+  if (action === "down" || action === "up" || action === "top" || action === "bottom") {
+    return [{ t: "move", to: action }];
+  }
+  return null;
+}
+
+/** Annotation navigation, deletion, and submit: one path for plan and diff. */
+function annotationCluster(state: KeyState, action: string | undefined): Intent[] | null {
+  if (action === "next_annotation" || action === "prev_annotation") {
+    if (!state.annotationCount) return status("no annotations");
+    return [{ t: action === "next_annotation" ? "nextAnn" : "prevAnn" }];
+  }
+  if (action === "delete_annotation") {
+    if (state.resolved || !state.hasFocusedAnnotation) return [];
+    return [{ t: "removeAnnotation" }];
+  }
+  if (action === "submit") return state.resolved ? [] : [{ t: "openSubmit" }];
+  return null;
+}

package/src/session-controller.ts

@@ -0,0 +1,345 @@
+/**
+ * The review-session controller (#70): every daemon round-trip and mutation
+ * verb behind one React-free object. It owns connect/autostart/subscribe,
+ * the session/inbox/status/error snapshot, optimistic apply, the mutation
+ * verbs (cut/edit/annotate/submit/...), and the post-submit completion
+ * lifecycle including the notes-vault export and the herdr return-focus.
+ * App subscribes to snapshots and keeps only view state.
+ */
+
+import { DaemonClient } from "@cueloop/daemon/client";
+import {
+  cutBlock,
+  makeAnchor,
+  newAnnotationId,
+  restoreBlock,
+  restoreLine,
+  type ReviewSession,
+  type VerdictKind,
+} from "@cueloop/schema";
+import { Registry, type Exporter } from "@cueloop/extension-api";
+import { createObsidianExtension, shouldExport, type ObsidianConfig } from "@cueloop/integration-obsidian";
+import { buildDisplay, nextWorkBlock, type DisplayBlock } from "./view";
+import { diffRowAnchor, diffRows, type DiffRow } from "./view-diff";
+import { editInEditor } from "./editor";
+import { focusHerdrPane, returnPaneFor } from "./herdr";
+import { persistAutoClose, type AutoClose, type CueloopConfig } from "./config";
+
+/**
+ * Post-submit lifecycle (a review pane should hand you back to the agent,
+ * not linger): idle → prompt (auto-close off: offer the choice) or
+ * counting (configured delay) → exit. esc dismisses to the resolved view.
+ */
+export type Completion =
+  | { phase: "idle" }
+  | { phase: "prompt" }
+  | { phase: "counting"; remaining: number }
+  | { phase: "dismissed" };
+
+export interface ControllerSnapshot {
+  session: ReviewSession | null;
+  inbox: ReviewSession[] | null;
+  status: string;
+  error: string | null;
+  completion: Completion;
+}
+
+export interface ReviewControllerOptions {
+  home?: string;
+  sessionId?: string;
+  /** Observer mode: stored for the key reducer's read-only gate. */
+  readOnly?: boolean;
+  onExit?: (code: number) => void;
+}
+
+export interface ReviewController {
+  readonly readOnly: boolean;
+  /** Snapshot listeners (stable identity - safe for useSyncExternalStore). */
+  subscribe(listener: () => void): () => void;
+  getSnapshot(): ControllerSnapshot;
+  /** Dial the daemon (autostart), subscribe to events, fetch session or inbox. */
+  connect(): void;
+  close(): void;
+  /** Loaded config parts the controller acts on: auto-close and exporters. */
+  applyConfig(cfg: CueloopConfig): void;
+  setStatus(msg: string): void;
+  /** Derived projections, cached per session identity. */
+  display(): DisplayBlock[];
+  rows(): DiffRow[];
+  working(): string;
+  /** Open a session from the inbox. */
+  open(id: string): void;
+  /** Cut the block under the cursor, or restore a cut one. */
+  cut(dispIdx: number): void;
+  /** The $EDITOR hand-off on the working copy. */
+  edit(): void;
+  /** Anchor and store an annotation; both plan and diff anchor constructions. */
+  annotate(kind: "comment" | "suggestion", dispIdx: number, start: number, end: number, body: string): void;
+  removeAnnotation(id: string): void;
+  setWorkingCopy(content: string | undefined): void;
+  /** Resolve the review, run the export, start the completion hand-back. */
+  submit(verdict: VerdictKind, summary: string): void;
+  /** Close the review and, inside herdr, bounce focus back to the agent. */
+  finishReview(): void;
+  dismissCompletion(): void;
+  /** From the completion prompt: persist auto-close and start the countdown. */
+  optInAutoClose(): void;
+}
+
+export function createReviewController(opts: ReviewControllerOptions): ReviewController {
+  return new Controller(opts);
+}
+
+class Controller implements ReviewController {
+  readonly readOnly: boolean;
+  private client: DaemonClient | null = null;
+  private closed = false;
+  private snap: ControllerSnapshot = {
+    session: null,
+    inbox: null,
+    status: "",
+    error: null,
+    completion: { phase: "idle" },
+  };
+  private listeners = new Set<() => void>();
+  private autoClose: AutoClose = "off";
+  private obsidian: ObsidianConfig | null = null;
+  private exporters = new Map<string, Exporter>();
+  private countdown: ReturnType<typeof setTimeout> | undefined;
+  /** Projections keyed by session identity so renders reuse one computation. */
+  private derivedFor: ReviewSession | null = null;
+  private derived: { display: DisplayBlock[]; rows: DiffRow[] } = { display: [], rows: [] };
+
+  constructor(private readonly opts: ReviewControllerOptions) {
+    this.readOnly = opts.readOnly ?? false;
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  getSnapshot = (): ControllerSnapshot => this.snap;
+
+  private update(patch: Partial<ControllerSnapshot>): void {
+    this.snap = { ...this.snap, ...patch };
+    for (const l of this.listeners) l();
+  }
+
+  connect(): void {
+    void (async () => {
+      try {
+        const client = await DaemonClient.connect({ home: this.opts.home, autostart: true });
+        if (this.closed) return void client.close();
+        this.client = client;
+        client.onEvent((e) => {
+          // another controller/observer changed state: re-fetch
+          const s = this.snap.session;
+          if (s && e.sessionId === s.id) void this.refreshSession(s.id);
+          if (!this.opts.sessionId) void this.refreshInbox();
+        });
+        await client.subscribe();
+        if (this.opts.sessionId) {
+          this.update({ session: await client.sessionGet(this.opts.sessionId) });
+        } else {
+          this.update({ inbox: await client.sessionList({ status: "pending" }) });
+        }
+      } catch (err) {
+        this.update({ error: err instanceof Error ? err.message : String(err) });
+      }
+    })();
+  }
+
+  close(): void {
+    this.closed = true;
+    clearTimeout(this.countdown);
+    this.client?.close();
+  }
+
+  applyConfig(cfg: CueloopConfig): void {
+    this.autoClose = cfg.ui.autoClose;
+    this.obsidian = cfg.integrations.obsidian;
+    // bundled integrations register through the public extension API
+    const registry = new Registry();
+    void registry.load("obsidian", createObsidianExtension(cfg.integrations.obsidian)).then((rec) => {
+      this.exporters = rec.exporters;
+    });
+  }
+
+  setStatus(msg: string): void {
+    this.update({ status: msg });
+  }
+
+  // ── derived projections ─────────────────────
+  private ensureDerived(): void {
+    const s = this.snap.session;
+    if (this.derivedFor === s) return;
+    this.derivedFor = s;
+    this.derived = {
+      display: s ? buildDisplay(s.artifact.content, s.workingCopy) : [],
+      rows: s && s.artifact.type === "diff" ? diffRows(s.artifact.content) : [],
+    };
+  }
+
+  display(): DisplayBlock[] {
+    this.ensureDerived();
+    return this.derived.display;
+  }
+
+  rows(): DiffRow[] {
+    this.ensureDerived();
+    return this.derived.rows;
+  }
+
+  working(): string {
+    const s = this.snap.session;
+    return s ? (s.workingCopy ?? s.artifact.content) : "";
+  }
+
+  private async refreshSession(id: string): Promise<void> {
+    if (this.client) this.update({ session: await this.client.sessionGet(id) });
+  }
+
+  private async refreshInbox(): Promise<void> {
+    if (this.client) this.update({ inbox: await this.client.sessionList({ status: "pending" }) });
+  }
+
+  /** Optimistic apply: the daemon response is the next session snapshot. */
+  private apply(p: Promise<ReviewSession>): void {
+    p.then((session) => this.update({ session })).catch((e: unknown) =>
+      this.setStatus(String(e instanceof Error ? e.message : e)),
+    );
+  }
+
+  // ── verbs ───────────────────────────────────
+  open(id: string): void {
+    const cached = this.snap.inbox?.find((s) => s.id === id);
+    if (cached) this.update({ session: cached });
+    else void this.refreshSession(id);
+  }
+
+  cut(dispIdx: number): void {
+    const session = this.snap.session;
+    if (!session || session.status === "resolved") return;
+    const d = this.display()[dispIdx];
+    if (!d) return;
+    const working = this.working();
+    if (d.type === "del") {
+      const line = restoreLine(nextWorkBlock(this.display(), dispIdx), working.split("\n").length);
+      // restoreBlock returns undefined when the block structure round-trips
+      // to the submitted revision - the working copy is gone
+      const restored = restoreBlock(session.artifact.content, working, d.base!, line);
+      this.setWorkingCopy(restored);
+      this.setStatus("cut restored");
+    } else if (d.work) {
+      this.setWorkingCopy(cutBlock(working, d.work));
+      this.setStatus("block cut - it serializes into the diff");
+    }
+  }
+
+  edit(): void {
+    const session = this.snap.session;
+    if (!session || session.status === "resolved") return;
+    try {
+      const result = editInEditor(this.working(), "plan.md");
+      if (result.changed) {
+        this.setWorkingCopy(result.content);
+        this.setStatus("edits tracked - one diff");
+      } else this.setStatus("no changes");
+    } catch (err) {
+      this.setStatus(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  annotate(kind: "comment" | "suggestion", dispIdx: number, start: number, end: number, body: string): void {
+    const session = this.snap.session;
+    if (!session) return;
+    let anchor;
+    if (session.artifact.type === "diff") {
+      anchor = { ...diffRowAnchor(this.rows(), dispIdx), blockIndex: dispIdx };
+    } else {
+      const display = this.display();
+      const workBlocks = display.filter((d) => d.work).map((d) => d.work!);
+      const workIdx = display.slice(0, dispIdx + 1).filter((d) => d.work).length - 1;
+      anchor = makeAnchor(workBlocks, workIdx, start, end);
+    }
+    this.apply(
+      this.client!.sessionAnnotate(session.id, {
+        id: newAnnotationId(),
+        kind,
+        anchor,
+        body,
+      }),
+    );
+    this.setStatus(kind === "suggestion" ? "suggestion added - the agent applies it" : "comment added");
+  }
+
+  removeAnnotation(id: string): void {
+    const session = this.snap.session;
+    if (!session) return;
+    this.apply(this.client!.sessionRemoveAnnotation(session.id, id));
+    this.setStatus("annotation deleted");
+  }
+
+  setWorkingCopy(content: string | undefined): void {
+    const session = this.snap.session;
+    if (!session) return;
+    this.apply(this.client!.sessionSetWorkingCopy(session.id, content));
+  }
+
+  submit(verdict: VerdictKind, summary: string): void {
+    const session = this.snap.session;
+    if (!session) return;
+    this.client!.sessionResolve(session.id, verdict, summary)
+      .then((resolved) => {
+        this.update({ session: resolved, status: `review submitted - ${verdict.replace("_", " ")}` });
+        // notes-vault export: guarded by config, default is manual (no-op)
+        const obsidian = this.obsidian;
+        const exporter = this.exporters.get("obsidian");
+        if (obsidian && exporter && shouldExport(obsidian.exportOn, verdict)) {
+          void exporter(resolved).then((r) => {
+            this.setStatus(r.success && r.path ? `exported to ${r.path}` : `export failed: ${r.error ?? "unknown"}`);
+          });
+        }
+        // hand the reviewer back to the agent: prompt or count down per config;
+        // inside herdr with a known return pane, closing is the default
+        const delay = this.autoClose;
+        const returns = returnPaneFor(resolved.artifact.meta.herdrPane) !== undefined;
+        if (delay === 0) this.finishReview();
+        else if (typeof delay === "number") this.startCounting(delay);
+        else if (returns) this.startCounting(3);
+        else this.update({ completion: { phase: "prompt" } });
+      })
+      .catch((e: unknown) => this.setStatus(String(e instanceof Error ? e.message : e)));
+  }
+
+  // ── completion hand-back ────────────────────
+  private startCounting(remaining: number): void {
+    if (remaining <= 0) return this.finishReview();
+    this.update({ completion: { phase: "counting", remaining } });
+    this.countdown = setTimeout(() => this.startCounting(remaining - 1), 1000);
+  }
+
+  finishReview(): void {
+    clearTimeout(this.countdown);
+    const pane = returnPaneFor(this.snap.session?.artifact.meta.herdrPane);
+    if (pane) focusHerdrPane(pane);
+    this.opts.onExit?.(0);
+  }
+
+  dismissCompletion(): void {
+    clearTimeout(this.countdown);
+    this.update({ completion: { phase: "dismissed" } });
+  }
+
+  optInAutoClose(): void {
+    // opt in: close in 3s from now on, persisted to the user config
+    try {
+      persistAutoClose(3);
+    } catch {
+      // a read-only config dir must not block closing the review
+    }
+    this.autoClose = 3;
+    this.startCounting(3);
+  }
+}

package/src/view.test.ts

@@ -2,17 +2,15 @@ import { describe, expect, test } from "bun:test";
 import {
   blockRuns,
   buildDisplay,
-  cutBlock,
   displayText,
   marksByDisplay,
+  nextWorkBlock,
   overlayMarks,
-  restoreBlock,
-  restoreLine,
   spanKey,
   startSpan,
   wrapRuns,
 } from "./view";
-import { parseBlocks, type Annotation } from "@cueloop/schema";
+import { cutBlock, parseBlocks, restoreBlock, restoreLine, type Annotation } from "@cueloop/schema";
 
 const BASE = `# Plan
 
@@ -150,8 +148,10 @@ describe("cut / restore round-trip", () => {
     expect(cut).not.toContain("second item");
     const display = buildDisplay(BASE, cut);
     const delIdx = display.findIndex((d) => d.type === "del");
-    const line = restoreLine(display, delIdx, cut.split("\n").length);
-    const restored = restoreBlock(cut, "- second item", line);
+    const line = restoreLine(nextWorkBlock(display, delIdx), cut.split("\n").length);
+    // undefined = the working copy round-tripped back to the submitted revision
+    const restored = restoreBlock(BASE, cut, li, line);
+    expect(restored).toBeUndefined();
     expect(buildDisplay(BASE, restored).every((d) => d.type === "same")).toBe(true);
   });
 });