reviewzy 0.1.0 → 0.2.0

package/src/dashboard/word-diff.ts

@@ -0,0 +1,89 @@
+/**
+ * The word-level diff between the anchor text and the proposed text, computed server-side at
+ * render time so the marks need no client js. Whitespace-token based: the split keeps whitespace
+ * runs as their own tokens, so both streams re-join to their exact input, bytes included.
+ */
+
+/** One token of a diffed string, carrying its mark. Whitespace runs are tokens too, always `same` when both sides share them. */
+export type WordDiffToken = {
+  readonly text: string;
+  readonly kind: "same" | "removed" | "added";
+};
+
+export type WordDiff = {
+  /** The anchor text tokenized: tokens the proposal does not keep are `removed`, the rest `same`. */
+  readonly before: readonly WordDiffToken[];
+  /** The proposal tokenized: tokens the anchor did not have are `added`, the rest `same`. */
+  readonly after: readonly WordDiffToken[];
+};
+
+/** Splits on whitespace boundaries, keeping the runs: `"a b"` becomes `["a", " ", "b"]`. */
+function tokenize(text: string): string[] {
+  return text.split(/(\s+)/).filter((token) => token !== "");
+}
+
+/**
+ * The LCS table is quadratic in token count, and the anchor is agent-controlled with no length
+ * cap, so past this cell ceiling the walk is skipped: each side reads fully changed, which is
+ * honest (no word is claimed unchanged) and renders in linear time.
+ */
+const MAX_LCS_CELLS = 1_000_000;
+
+/**
+ * A longest-common-subsequence walk over the two token streams: a token both sides share is
+ * `same`, one only the anchor has is `removed`, one only the proposal has is `added`. Identical
+ * strings produce all-`same` streams, so nothing renders a mark.
+ */
+export function diffWords(before: string, after: string): WordDiff {
+  const a = tokenize(before);
+  const b = tokenize(after);
+
+  if (a.length * b.length > MAX_LCS_CELLS) {
+    return {
+      before: a.map((text) => ({ text, kind: "removed" as const })),
+      after: b.map((text) => ({ text, kind: "added" as const })),
+    };
+  }
+
+  // dp[i][j] is the LCS length of a[i:] against b[j:], filled bottom-up so the walk can pick the
+  // branch that keeps the longest match. One flat typed array: 8 bytes a cell, no nested rows.
+  const stride = b.length + 1;
+  const dp = new Float64Array((a.length + 1) * stride);
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      const below = dp[(i + 1) * stride + j]!;
+      const right = dp[i * stride + j + 1]!;
+      dp[i * stride + j] = a[i] === b[j] ? below + 1 : Math.max(below, right);
+    }
+  }
+
+  const beforeTokens: WordDiffToken[] = [];
+  const afterTokens: WordDiffToken[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      beforeTokens.push({ text: a[i]!, kind: "same" });
+      afterTokens.push({ text: b[j]!, kind: "same" });
+      i++;
+      j++;
+    } else if (dp[(i + 1) * stride + j]! >= dp[i * stride + j + 1]!) {
+      // Skipping the anchor's token keeps at least as long a match: it is removed.
+      beforeTokens.push({ text: a[i]!, kind: "removed" });
+      i++;
+    } else {
+      afterTokens.push({ text: b[j]!, kind: "added" });
+      j++;
+    }
+  }
+  while (i < a.length) {
+    beforeTokens.push({ text: a[i]!, kind: "removed" });
+    i++;
+  }
+  while (j < b.length) {
+    afterTokens.push({ text: b[j]!, kind: "added" });
+    j++;
+  }
+
+  return { before: beforeTokens, after: afterTokens };
+}

package/src/db/human-save.ts

@@ -240,3 +240,115 @@ export function listRevisions(store: Store, entryId: string): RevisionRow[] {
     )
     .all(entryId) as RevisionRow[];
 }
+
+/**
+ * The tolerant parse for `entries.images`, mirroring `parseConstraints`: the column holds foreign
+ * data (it is also fed by the wire), and an unparseable or shape-broken value must read as no
+ * images, never as a 500. Non-string items are dropped rather than propagated.
+ */
+export function parseEntryImages(json: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((item): item is string => typeof item === "string");
+}
+
+/** The per-entry image cap `docs/mcp-contract.md` pins for `images`; the wire's boundary carries the same number in its own layer. */
+const MAX_ENTRY_IMAGES = 8;
+
+/** Everything the image writes refuse; the dashboard's upload and remove routes format the messages. */
+export type ImageWriteRefusal =
+  | { readonly kind: "unknown" }
+  | { readonly kind: "too_many" }
+  | { readonly kind: "no_image"; readonly index: number };
+
+/**
+ * Appends one image the human uploaded to the entry's image list. A note-like write, not a save:
+ * it works on every status, writes no revision row, changes no status, and fires no status event
+ * (a waiter cares about approval, not about a new screenshot). `updated_at` moves so the row
+ * reflects the write. The data url already passed the route's mime and size checks, and the
+ * stored list must stay inside the contract's image cap.
+ *
+ * The read and the write share one immediate transaction: a deferred one would let two racing
+ * uploads (a double submit) both read the old list and drop one image on the later write, while
+ * the immediate lock serializes them at the read.
+ */
+export function appendEntryImage(
+  store: Store,
+  id: string,
+  dataUrl: string,
+): { readonly ok: true } | { readonly ok: false; readonly refusal: ImageWriteRefusal } {
+  const write = store.db.transaction(() => {
+    const row = store.db.query("SELECT images FROM entries WHERE id = ?").get(id) as { images: string } | null;
+    if (row === null) return { ok: false as const, refusal: { kind: "unknown" as const } };
+
+    const images = parseEntryImages(row.images);
+    if (images.length >= MAX_ENTRY_IMAGES) {
+      return { ok: false as const, refusal: { kind: "too_many" as const } };
+    }
+    images.push(dataUrl);
+    store.db.run("UPDATE entries SET images = ?, updated_at = ? WHERE id = ?", [
+      JSON.stringify(images),
+      Date.now(),
+      id,
+    ]);
+    return { ok: true as const };
+  });
+  return write.immediate();
+}
+
+/**
+ * Removes one image by its index in the stored array. Same write class as `appendEntryImage`: no
+ * revision, no status change, no event; `updated_at` moves, and the read + write share one
+ * immediate transaction for the same double-submit race the append guards. An index past either
+ * end is a refusal carrying the index the route's message names.
+ */
+export function removeEntryImage(
+  store: Store,
+  id: string,
+  index: number,
+): { readonly ok: true } | { readonly ok: false; readonly refusal: ImageWriteRefusal } {
+  const write = store.db.transaction(() => {
+    const row = store.db.query("SELECT images FROM entries WHERE id = ?").get(id) as { images: string } | null;
+    if (row === null) return { ok: false as const, refusal: { kind: "unknown" as const } };
+
+    const images = parseEntryImages(row.images);
+    if (index < 0 || index >= images.length) {
+      return { ok: false as const, refusal: { kind: "no_image" as const, index } };
+    }
+    images.splice(index, 1);
+    store.db.run("UPDATE entries SET images = ?, updated_at = ? WHERE id = ?", [
+      JSON.stringify(images),
+      Date.now(),
+      id,
+    ]);
+    return { ok: true as const };
+  });
+  return write.immediate();
+}
+
+/**
+ * Saves the human's own notes. Deliberately unlike `saveHumanText`: the notes are a scratchpad, so
+ * the write works on every status (an applied or rejected entry's notes stay editable), an empty
+ * string clears them rather than refusing, and nothing else moves — no revision row (only prose
+ * saves make history), no status change, no status event (a waiter cares about approval, not about
+ * a note). `updated_at` moves so the row reflects the write. The only refusal is an unknown id.
+ */
+export function saveHumanNotes(
+  store: Store,
+  input: { readonly id: string; readonly notes: string },
+): { readonly ok: true } | { readonly ok: false; readonly refusal: { readonly kind: "unknown" } } {
+  const row = store.db.query("SELECT id FROM entries WHERE id = ?").get(input.id) as { id: string } | null;
+  if (row === null) return { ok: false, refusal: { kind: "unknown" } };
+
+  store.db.run("UPDATE entries SET human_notes = ?, updated_at = ? WHERE id = ?", [
+    input.notes,
+    Date.now(),
+    input.id,
+  ]);
+  return { ok: true };
+}

package/src/db/migrations.ts

@@ -146,4 +146,42 @@ export const MIGRATIONS: Migration[] = [
       ALTER TABLE entries_archive ADD COLUMN applied_hash TEXT;
     `,
   },
+  {
+    version: 4,
+    name: "entry-title",
+    sql: `
+      -- An optional human-readable label the dashboard shows in place of the file basename, so a
+      -- row reads as what it changes rather than where it lives (cloudy, 2026-08-20). Nullable:
+      -- an entry without one falls back to its anchor text at render. The archive mirrors entries
+      -- column-for-column, so it gains the column too.
+      ALTER TABLE entries ADD COLUMN title TEXT;
+      ALTER TABLE entries_archive ADD COLUMN title TEXT;
+    `,
+  },
+  {
+    version: 5,
+    name: "entry-images",
+    sql: `
+      -- Screenshots and links attached to an entry, filed by agents and appended to by the human
+      -- on the dashboard. A json array of strings, each a data:image/ data url or an http(s) url;
+      -- the wire boundary enforces the shape (max 8, max 5 MiB each). NOT NULL with an empty
+      -- array default: an entry without images stores [] like the other json columns. The archive
+      -- mirrors entries column-for-column, so it gains the column too.
+      ALTER TABLE entries ADD COLUMN images TEXT NOT NULL DEFAULT '[]';
+      ALTER TABLE entries_archive ADD COLUMN images TEXT NOT NULL DEFAULT '[]';
+    `,
+  },
+  {
+    version: 6,
+    name: "entry-human-notes",
+    sql: `
+      -- The human's own scratchpad, dashboard-only: agents can neither set nor read it, so the
+      -- filing insert leaves it NULL and the list_entries tool projects it out of the wire row.
+      -- Nullable, unlike the agent-fed json columns: no agent ever sends a value, and NULL is
+      -- what renders as "no notes yet". The archive mirrors entries column-for-column, so it
+      -- gains the column too.
+      ALTER TABLE entries ADD COLUMN human_notes TEXT;
+      ALTER TABLE entries_archive ADD COLUMN human_notes TEXT;
+    `,
+  },
 ];

package/src/db/queries.ts

@@ -8,14 +8,15 @@ export type EntryStatus = "draft" | "approved" | "applied" | "rejected";
 /**
  * One entry as it crosses into the store: every field already typed, hashed, and stringified.
  * The json boundary belongs to the tool that reads the wire (`src/mcp/file-entries.ts`); nothing
- * here re-parses what it already accepted. `agentDraft`, `contextJson`, and `constraintsJson` are
- * null when the caller did not send the field: a first filing stores the empty default, and a
- * draft re-file keeps the stored value (the schema refuses explicit null, so no caller can
- * express a wipe).
+ * here re-parses what it already accepted. `agentDraft`, `contextJson`, `constraintsJson`, and
+ * `imagesJson` are null when the caller did not send the field: a first filing stores the empty
+ * default, and a draft re-file keeps the stored value (the schema refuses explicit null, so no
+ * caller can express a wipe).
  */
 export type NewEntry = {
   readonly repo: string;
   readonly file: string;
+  readonly title: string | null;
   readonly anchorText: string;
   readonly anchorBefore: string;
   readonly anchorAfter: string;
@@ -24,6 +25,7 @@ export type NewEntry = {
   readonly agentDraft: string | null;
   readonly contextJson: string | null;
   readonly constraintsJson: string | null;
+  readonly imagesJson: string | null;
 };
 
 export type FiledEntry = {
@@ -48,6 +50,7 @@ export type EntryRow = {
   readonly batch_id: string;
   readonly repo: string;
   readonly file: string;
+  readonly title: string | null;
   readonly anchor_text: string;
   readonly anchor_before: string;
   readonly anchor_after: string;
@@ -61,6 +64,8 @@ export type EntryRow = {
   readonly filed_by: string | null;
   readonly stale_note: string | null;
   readonly applied_hash: string | null;
+  readonly images: string;
+  readonly human_notes: string | null;
   readonly created_at: number;
   readonly updated_at: number;
   readonly applied_at: number | null;
@@ -189,16 +194,17 @@ function fileOneEntry(
     const now = Date.now();
     db.run(
       `INSERT INTO entries (
-        id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after,
+        id, project_id, batch_id, repo, file, title, anchor_text, anchor_before, anchor_after,
         anchor_hash, file_hash, agent_draft, human_text, status, context, constraints,
-        filed_by, stale_note, created_at, updated_at, applied_at, archived_at
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 'draft', ?, ?, ?, NULL, ?, ?, NULL, NULL)`,
+        filed_by, stale_note, images, created_at, updated_at, applied_at, archived_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, 'draft', ?, ?, ?, NULL, ?, ?, ?, NULL, NULL)`,
       [
         id,
         projectId,
         batchId,
         entry.repo,
         entry.file,
+        entry.title,
         entry.anchorText,
         entry.anchorBefore,
         entry.anchorAfter,
@@ -208,6 +214,7 @@ function fileOneEntry(
         entry.contextJson ?? "{}",
         entry.constraintsJson ?? "{}",
         filedBy,
+        entry.imagesJson ?? "[]",
         now,
         now,
       ],
@@ -219,8 +226,8 @@ function fileOneEntry(
     // `COALESCE(?, column)`: a field the newer call did not carry (null) keeps the stored value.
     // The schema refuses explicit null, so a re-file can only move the fields it names.
     db.run(
-      "UPDATE entries SET agent_draft = COALESCE(?, agent_draft), context = COALESCE(?, context), constraints = COALESCE(?, constraints), updated_at = ? WHERE id = ?",
-      [entry.agentDraft, entry.contextJson, entry.constraintsJson, Date.now(), existing.id],
+      "UPDATE entries SET agent_draft = COALESCE(?, agent_draft), context = COALESCE(?, context), constraints = COALESCE(?, constraints), title = COALESCE(?, title), images = COALESCE(?, images), updated_at = ? WHERE id = ?",
+      [entry.agentDraft, entry.contextJson, entry.constraintsJson, entry.title, entry.imagesJson, Date.now(), existing.id],
     );
     return { id: existing.id, status: "draft", deduped: true, updated: true };
   }
@@ -254,9 +261,10 @@ const APPROVED_PAGE_SIZE = 50;
 
 /** The columns `docs/mcp-contract.md`'s entry schema names; the one place the output row's shape is spelled out in SQL. */
 const ENTRY_COLUMNS = [
-  "id", "project_id", "batch_id", "repo", "file", "anchor_text", "anchor_before",
-  "anchor_after", "anchor_hash", "file_hash", "agent_draft", "human_text", "status",
-  "context", "constraints", "filed_by", "stale_note", "applied_hash", "created_at", "updated_at", "applied_at", "archived_at",
+  "id", "project_id", "batch_id", "repo", "file", "title", "anchor_text", "anchor_before",
+  "anchor_after", "anchor_hash", "file_hash", "agent_draft", "human_notes", "human_text", "status",
+  "context", "constraints", "filed_by", "stale_note", "applied_hash", "images", "created_at",
+  "updated_at", "applied_at", "archived_at",
 ] as const;
 
 /**
@@ -304,6 +312,21 @@ export function listEntries(store: Store, filter: ListEntriesFilter): ListEntrie
   return { rows, nextCursor };
 }
 
+/**
+ * The entries immediately before and after `id` in the ascending-id walk the list renders, for the
+ * editor's full-height prev/next rails; null at either boundary. The `id` column is a primary key,
+ * so both comparisons run on its unique index.
+ */
+export function adjacentEntryIds(store: Store, id: string): { prevId: string | null; nextId: string | null } {
+  const prev = store.db.query("SELECT id FROM entries WHERE id < ? ORDER BY id DESC LIMIT 1").get(id) as
+    | { id: string }
+    | null;
+  const next = store.db.query("SELECT id FROM entries WHERE id > ? ORDER BY id ASC LIMIT 1").get(id) as
+    | { id: string }
+    | null;
+  return { prevId: prev?.id ?? null, nextId: next?.id ?? null };
+}
+
 /**
  * The `fetch_approved` read. The status is not a filter: the tool's invariant is `'approved'`
  * (a draft, applied, or rejected row never leaves this query), and the page size is the contract's

package/src/db/sweep.ts

@@ -55,12 +55,12 @@ export function sweepArchive(store: Store, now: number, archiveAfterDays: number
       `INSERT INTO entries_archive (
         id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after,
         anchor_hash, file_hash, agent_draft, human_text, status, context, constraints,
-        filed_by, stale_note, applied_hash, created_at, updated_at, applied_at, archived_at
+        filed_by, stale_note, applied_hash, images, human_notes, created_at, updated_at, applied_at, archived_at
       )
       SELECT
         id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after,
         anchor_hash, file_hash, agent_draft, human_text, status, context, constraints,
-        filed_by, stale_note, applied_hash, created_at, updated_at, applied_at, ?
+        filed_by, stale_note, applied_hash, images, human_notes, created_at, updated_at, applied_at, ?
       FROM entries
       WHERE ${EXPIRED_APPLIED}`,
       [now, cutoff],

package/src/mcp/file-entries.ts

@@ -42,6 +42,7 @@ const ConstraintsJson = z.strictObject({
 const FileEntryArgs = z.object({
   repo: z.string().min(1),
   file: z.string().min(1),
+  title: z.string().min(1).optional(),
   anchor_text: z.string().min(1),
   anchor_before: z.string().optional(),
   anchor_after: z.string().optional(),
@@ -50,6 +51,7 @@ const FileEntryArgs = z.object({
   file_hash: z.string().optional(),
   context: z.unknown().optional(),
   constraints: z.unknown().optional(),
+  images: z.unknown().optional(),
 });
 
 const FiledOutput = z.object({
@@ -84,6 +86,10 @@ const CONSTRAINT_FIX: Record<string, string> = {
   notes: "send constraints.notes as a string",
 };
 
+/** The caps `docs/mcp-contract.md` pins for `images`: at most 8 per entry, each at most 5 MiB. */
+const MAX_IMAGES_PER_ENTRY = 8;
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+
 /** Turns zod's issues into the named-field refusal the contract's error row promises. */
 function refuseConstraints(index: number, file: string, anchorText: string, issues: readonly z.ZodIssue[]): never {
   const where = entryName(index, file, anchorText);
@@ -123,6 +129,50 @@ function validateEntry(index: number, raw: z.output<typeof FileEntryArgs>): NewE
     refuseConstraints(index, raw.file, raw.anchor_text, constraints.error.issues);
   }
 
+  // Held loose like context and constraints, so the refusal names the entry and the fix instead
+  // of stopping at the sdk's field-path error. Absent (or explicit null) means "the newer call
+  // does not carry this field": a draft re-file then keeps the stored images.
+  let imagesJson: string | null;
+  if (raw.images == null) {
+    imagesJson = null;
+  } else {
+    if (!Array.isArray(raw.images)) {
+      refuse(
+        where,
+        "images must be an array of image urls or data urls",
+        'send an array such as ["https://example.com/screenshot.png"], or omit images',
+      );
+    }
+    if (raw.images.length > MAX_IMAGES_PER_ENTRY) {
+      refuse(
+        where,
+        `images has ${raw.images.length} items; the limit is ${MAX_IMAGES_PER_ENTRY}`,
+        `send at most ${MAX_IMAGES_PER_ENTRY} images per entry`,
+      );
+    }
+    raw.images.forEach((item, imageIndex) => {
+      if (typeof item !== "string") {
+        refuse(where, `images[${imageIndex}] must be a string`, "send each image as a string url or data url");
+      }
+      if (!item.startsWith("data:image/") && !/^https?:\/\//.test(item)) {
+        refuse(
+          where,
+          `images[${imageIndex}] must start with "data:image/" or an http(s) url, got "${item.slice(0, 40)}"`,
+          "send a data:image/ data url or an http(s) url",
+        );
+      }
+      const bytes = Buffer.byteLength(item, "utf8");
+      if (bytes > MAX_IMAGE_BYTES) {
+        refuse(
+          where,
+          `images[${imageIndex}] is ${bytes} bytes; the limit is ${MAX_IMAGE_BYTES} bytes (5 MiB)`,
+          "send a smaller image, or link an http(s) url instead",
+        );
+      }
+    });
+    imagesJson = JSON.stringify(raw.images);
+  }
+
   let fileHash: string;
   if (raw.file_content !== undefined && raw.file_hash !== undefined) {
     refuse(
@@ -152,6 +202,7 @@ function validateEntry(index: number, raw: z.output<typeof FileEntryArgs>): NewE
   return {
     repo: raw.repo,
     file: raw.file,
+    title: raw.title ?? null,
     anchorText: raw.anchor_text,
     anchorBefore: raw.anchor_before ?? "",
     anchorAfter: raw.anchor_after ?? "",
@@ -162,6 +213,7 @@ function validateEntry(index: number, raw: z.output<typeof FileEntryArgs>): NewE
     // re-file then keeps the stored value, per the COALESCE in src/db/queries.ts.
     contextJson: raw.context == null ? null : JSON.stringify(context.data),
     constraintsJson: raw.constraints == null ? null : JSON.stringify(constraints.data),
+    imagesJson,
   };
 }
 
@@ -177,7 +229,7 @@ export function registerFileEntriesTool(server: McpServer, baseUrl: string, stor
     {
       title: "File entries for review",
       description:
-        "File draft entries for a human to author or approve. Each entry names one exact string to replace: repo (git remote url preferred), file path, anchor_text, and anchor_before/anchor_after context lines. Identity is (project, repo, file, sha256(anchor_text)): re-filing a known draft overwrites the agent draft, context, and constraints in place; an entry already approved, applied, or rejected is returned untouched with its own status, and a rejected anchor stays rejected — stop proposing a turned-down line. file provenance: send exactly one of file_content (the whole file at filing time; the server hashes it) or file_hash (its sha256 hex). constraints: {max_len?, placeholders?: string[], tone?, notes?} — a save breaking max_len or dropping a placeholder is refused later, so declare what the copy must keep. Keys the schema does not list are ignored.",
+        "File draft entries for a human to author or approve. One entry is one edit: anchor_text is the whole passage being replaced and agent_draft the proposed replacement; either may be a single line or span many lines, and a multi-line block is ONE entry, never one entry per line. Each entry names repo (git remote url preferred), file path, an optional title (a human-readable label the dashboard shows in place of the file path), anchor_text, and anchor_before/anchor_after context lines. Identity is (project, repo, file, sha256(anchor_text)): re-filing a known draft overwrites the agent draft, context, and constraints in place; an entry already approved, applied, or rejected is returned untouched with its own status, and a rejected anchor stays rejected — stop proposing a turned-down passage. file provenance: send exactly one of file_content (the whole file at filing time; the server hashes it) or file_hash (its sha256 hex). constraints: {max_len?, placeholders?: string[], tone?, notes?} — a save breaking max_len or dropping a placeholder is refused later, so declare what the copy must keep. images: up to 8 per entry, each a data:image/ data url or an http(s) url of at most 5 MiB, rendered on the dashboard. Keys the schema does not list are ignored. The dashboard shows entries in the order the agent sends them, so file the most important entries first.",
       inputSchema: z.object({
         project: z.string().min(1),
         entries: z.array(FileEntryArgs).min(1),

package/src/mcp/list-entries.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { listEntries, projectIdBySlug } from "../db/queries.ts";
+import type { EntryRow } from "../db/queries.ts";
 import type { Store } from "../db/store.ts";
 
 /**
@@ -18,13 +19,49 @@ const ListEntriesArgs = z.object({
   cursor: z.string().min(1).optional(),
 });
 
-/** The wire row is the stored row, `context` and `constraints` kept as their stored JSON strings — no re-parse on the way out. */
+/**
+ * The one mapping from stored rows to the wire shape: every field spelled out, so a new store
+ * column reaches the wire only when someone adds it here deliberately — `human_notes` must never
+ * (the contract pins it dashboard-only), and `images` is carried on purpose. The SDK passes
+ * structuredContent through untouched, so this projection is the strip, not the schema.
+ */
+function toWireEntry(row: EntryRow): z.infer<typeof Entry> {
+  return {
+    id: row.id,
+    project_id: row.project_id,
+    batch_id: row.batch_id,
+    repo: row.repo,
+    file: row.file,
+    title: row.title,
+    anchor_text: row.anchor_text,
+    anchor_before: row.anchor_before,
+    anchor_after: row.anchor_after,
+    anchor_hash: row.anchor_hash,
+    file_hash: row.file_hash,
+    agent_draft: row.agent_draft,
+    human_text: row.human_text,
+    status: row.status,
+    context: row.context,
+    constraints: row.constraints,
+    filed_by: row.filed_by,
+    stale_note: row.stale_note,
+    applied_hash: row.applied_hash,
+    images: row.images,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+    applied_at: row.applied_at,
+    archived_at: row.archived_at,
+  };
+}
+
+/** The wire row shape, `context`, `constraints`, and `images` kept as their stored JSON strings — no re-parse on the way out. */
 const Entry = z.object({
   id: z.string(),
   project_id: z.string(),
   batch_id: z.string(),
   repo: z.string(),
   file: z.string(),
+  title: z.string().nullable(),
   anchor_text: z.string(),
   anchor_before: z.string(),
   anchor_after: z.string(),
@@ -38,6 +75,7 @@ const Entry = z.object({
   filed_by: z.string().nullable(),
   stale_note: z.string().nullable(),
   applied_hash: z.string().nullable(),
+  images: z.string(),
   created_at: z.number(),
   updated_at: z.number(),
   applied_at: z.number().nullable(),
@@ -65,7 +103,7 @@ export function registerListEntriesTool(server: McpServer, store: Store): void {
     {
       title: "List entries for review",
       description:
-        "List entries in the review queue, ordered by ascending entry id (ulid, i.e. filing order) — the same order a cursor walk covers. Every filter is optional and they combine with AND: project (a slug with no project is refused: read tools never create one), status (draft, approved, applied, rejected), ids (exact entry ids), q (case-insensitive substring, ASCII-only case fold: a row matches when any of file, anchor_text, agent_draft, human_text contains it), limit (default 50, max 200 — a higher value is refused), cursor (keyset pagination: pass the previous page's next_cursor to continue from after the last entry returned). next_cursor is present only when the page returned exactly limit rows, meaning more may exist; absent means the walk is exhausted — stop paging then, never craft a cursor of your own. Each entry carries its stored fields as stored: id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after, anchor_hash, file_hash, agent_draft, human_text, status, context, constraints, filed_by, stale_note, applied_hash, created_at, updated_at, applied_at, archived_at — with context and constraints as their stored JSON strings, not parsed objects.",
+        "List entries in the review queue, ordered by ascending entry id (ulid, i.e. filing order) — the same order a cursor walk covers. Every filter is optional and they combine with AND: project (a slug with no project is refused: read tools never create one), status (draft, approved, applied, rejected), ids (exact entry ids), q (case-insensitive substring, ASCII-only case fold: a row matches when any of file, anchor_text, agent_draft, human_text contains it), limit (default 50, max 200 — a higher value is refused), cursor (keyset pagination: pass the previous page's next_cursor to continue from after the last entry returned). next_cursor is present only when the page returned exactly limit rows, meaning more may exist; absent means the walk is exhausted — stop paging then, never craft a cursor of your own. Each entry carries its stored fields as stored: id, project_id, batch_id, repo, file, title, anchor_text, anchor_before, anchor_after, anchor_hash, file_hash, agent_draft, human_text, status, context, constraints, filed_by, stale_note, applied_hash, images, created_at, updated_at, applied_at, archived_at — with context, constraints, and images as their stored JSON strings, not parsed objects. The human's own notes (human_notes) are dashboard-only and never appear in a listed entry.",
       inputSchema: ListEntriesArgs,
       outputSchema: ListEntriesOutput,
     },
@@ -95,7 +133,7 @@ export function registerListEntriesTool(server: McpServer, store: Store): void {
       // An exhausted walk carries no `next_cursor` key at all: absent is the signal to stop, so an
       // empty page must never smuggle one in.
       const output = {
-        entries: rows,
+        entries: rows.map(toWireEntry),
         ...(nextCursor === null ? {} : { next_cursor: nextCursor }),
       };
       return {

package/src/mcp/mark-applied.ts

@@ -81,7 +81,7 @@ export function registerMarkAppliedTool(server: McpServer, store: Store): void {
           refuse(
             `entry "${args.id}"`,
             "status rejected: rejected is terminal and silences the agent",
-            "file a new entry with a new anchor if the line still needs changing",
+            "file a new entry with a new anchor if the passage still needs changing",
           );
         }
         // The only pair left is an applied entry reported applied again: anchor_stale on an

package/src/mcp/route.ts

@@ -58,17 +58,14 @@ export function mountMcp(
   store: Store,
   notifier: Notifier = new Notifier({ config, baseUrl: config.baseUrl }),
 ): void {
-  // `legacy: 'reject'` is the whole of the revision guard, so the endpoint serves only the one
-  // revision `docs/mcp-contract.md` freezes. `supportedProtocolVersions` on the server cannot do
-  // it and is deliberately unset: the SDK's `installDiscoverHandler` unions its served modern
-  // revisions back into that array regardless of what was passed, and on a legacy leg
-  // (`Server._oninitialize`) the list only picks WHICH 2025-era revision to answer with —
-  // `legacyVersions[0] ?? LATEST_PROTOCOL_VERSION`, and `LATEST_PROTOCOL_VERSION` is
-  // `"2025-11-25"`. A modern-only list empties `legacyVersions`, which is exactly what reaches
-  // that hardcoded fallback, so narrowing it is what would serve one.
+  // The native surface is the one revision `docs/mcp-contract.md` freezes, but `legacy: 'reject'`
+  // locked out the claude harness fleet, whose mcp client negotiates `2025-11-25` (measured
+  // 2026-08-21: 2.1.238 sends a legacy initialize and reads the refusal as a dead server).
+  // `legacy: 'stateless'` is the SDK default and answers 2025-era traffic from the same factory
+  // per request, so both legs stay stateless and no session is minted on either one.
   // The store is the daemon's own open handle (`startDaemon` opens it before the port binds), so
   // every tool call writes through the one connection the daemon will close on shutdown.
-  const handler = createMcpHandler(() => createMcpServer(config, store, notifier), { legacy: "reject" });
+  const handler = createMcpHandler(() => createMcpServer(config, store, notifier), { legacy: "stateless" });
 
   // The `Origin` rung is `originGate`, mounted app-wide in `createApp`; it runs before this
   // handler, so the pinned order (origin, then method, then credential) holds without a repeat of

package/src/mcp/server.ts

@@ -16,7 +16,7 @@ import { NAME, VERSION } from "../version.ts";
  */
 const INSTRUCTIONS = `reviewzy is a review queue for user-facing text. Agents draft, a human signs off.
 
-File the strings you want to change as draft entries against a project. A human authors or approves the wording on the dashboard, then you fetch those words back and apply them in place. You can create a draft, move an approved entry to applied, and report an anchor that no longer matches. You can never approve or reject an entry, and a rejected anchor stays rejected: re-filing it returns the existing entry instead of proposing the line again.`;
+File the text you want to change as draft entries against a project. One entry is one edit: anchor_text is the whole passage being replaced and agent_draft the proposed replacement; either may be a single line or span many lines, and a multi-line block is ONE entry, never one entry per line. A human authors or approves the wording on the dashboard, then you fetch those words back and apply them in place. You can create a draft, move an approved entry to applied, and report an anchor that no longer matches. You can never approve or reject an entry, and a rejected anchor stays rejected: re-filing it returns the existing entry instead of proposing the passage again.`;
 
 /**
  * A fresh server per request, since the 2026-07-28 revision is stateless and `createMcpHandler`