@vellumai/assistant 0.11.3 → 0.11.4-staging.2

package/src/plugins/__tests__/mcp-servers.test.ts

@@ -0,0 +1,371 @@
+/**
+ * Tests for reading plugin-declared MCP servers from a root `mcp.json`.
+ *
+ * The failure-isolation behaviour is the part worth pinning: the Agent
+ * Plugins spec says an invalid top-level manifest disables MCP for that
+ * plugin alone, and an invalid individual entry disables only that entry.
+ * A reader that threw on either would take every other plugin's servers
+ * out of `assistant mcp list` along with it.
+ */
+
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildServerId,
+  hasLoadableManifest,
+  interpolatePluginPaths,
+  readPluginMcpServers,
+} from "../mcp-servers.js";
+
+/** Build a throwaway plugins directory with the given plugin layouts. */
+function makePluginsDir(
+  plugins: Record<
+    string,
+    { mcpJson?: string; packageJson?: string; disabled?: boolean }
+  >,
+): string {
+  const root = mkdtempSync(join(tmpdir(), "vellum-plugin-mcp-"));
+  for (const [name, spec] of Object.entries(plugins)) {
+    const dir = join(root, name);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "package.json"),
+      spec.packageJson ?? JSON.stringify({ name, version: "1.0.0" }),
+    );
+    if (spec.mcpJson !== undefined) {
+      writeFileSync(join(dir, "mcp.json"), spec.mcpJson);
+    }
+    if (spec.disabled) {
+      writeFileSync(join(dir, ".disabled"), "");
+    }
+  }
+  return root;
+}
+
+const VALID_MANIFEST = JSON.stringify({
+  $schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  mcpServers: {
+    unabyss: { type: "streamable-http", url: "https://mcp.unabyss.com" },
+  },
+});
+
+describe("buildServerId", () => {
+  test("collapses the redundant case so tool names stay readable", () => {
+    // The id is embedded in every tool name as mcp__<id>__<tool>, so
+    // `unabyss__unabyss` would show up in the model's catalog.
+    expect(buildServerId("unabyss", "unabyss")).toEqual("unabyss");
+  });
+
+  test("qualifies with the plugin name when the keys differ", () => {
+    expect(buildServerId("acme", "deploy")).toEqual("acme__deploy");
+  });
+});
+
+describe("hasLoadableManifest", () => {
+  const base = {
+    name: "x",
+    target: "/p",
+    issues: [],
+    hasIcon: false,
+    source: "user" as const,
+    disabled: false,
+  };
+
+  test("accepts a manifest with a non-empty name, matching the runtime gate", () => {
+    expect(hasLoadableManifest({ ...base, packageJson: { name: "x" } })).toBe(
+      true,
+    );
+  });
+
+  test("rejects an unreadable or unparseable manifest", () => {
+    expect(hasLoadableManifest({ ...base, packageJson: null })).toBe(false);
+  });
+
+  test("rejects a manifest with no name", () => {
+    expect(
+      hasLoadableManifest({ ...base, packageJson: { version: "1.0.0" } }),
+    ).toBe(false);
+  });
+
+  test("rejects an empty name", () => {
+    expect(hasLoadableManifest({ ...base, packageJson: { name: "" } })).toBe(
+      false,
+    );
+  });
+});
+
+describe("interpolatePluginPaths", () => {
+  test("expands both spec-defined variables", () => {
+    expect(
+      interpolatePluginPaths("${PLUGIN_ROOT}/bin", "/p", "/p/data"),
+    ).toEqual("/p/bin");
+    expect(
+      interpolatePluginPaths("${PLUGIN_DATA}/db", "/p", "/p/data"),
+    ).toEqual("/p/data/db");
+  });
+
+  test("expands every occurrence, not just the first", () => {
+    expect(
+      interpolatePluginPaths("${PLUGIN_ROOT}:${PLUGIN_ROOT}", "/p", "/p/data"),
+    ).toEqual("/p:/p");
+  });
+
+  test("leaves unknown variables alone", () => {
+    expect(interpolatePluginPaths("${HOME}/x", "/p", "/p/data")).toEqual(
+      "${HOME}/x",
+    );
+  });
+});
+
+describe("readPluginMcpServers", () => {
+  test("reads a streamable-http server from a plugin manifest", () => {
+    const dir = makePluginsDir({ unabyss: { mcpJson: VALID_MANIFEST } });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+
+    expect(issues).toEqual([]);
+    expect(servers).toHaveLength(1);
+    expect(servers[0].id).toEqual("unabyss");
+    expect(servers[0].pluginName).toEqual("unabyss");
+    expect(servers[0].config.transport).toEqual({
+      type: "streamable-http",
+      url: "https://mcp.unabyss.com",
+    });
+  });
+
+  test("defaults plugin servers to low risk", () => {
+    // mcp.json has no risk field, so a host default applies. It is `low`
+    // because the review happens at install time — curated marketplace,
+    // SHA-pinned — rather than on every call.
+    const dir = makePluginsDir({ unabyss: { mcpJson: VALID_MANIFEST } });
+    const { servers } = readPluginMcpServers({ workspacePluginsDir: dir });
+    expect(servers[0].config.defaultRiskLevel).toEqual("low");
+  });
+
+  test("ignores a directory whose package.json is missing", () => {
+    // `listAllPlugins` reports a malformed directory rather than dropping
+    // it, but the runtime loader will never load one, so honoring its
+    // mcp.json would advertise a server no plugin stands behind.
+    const root = mkdtempSync(join(tmpdir(), "vellum-plugin-mcp-"));
+    const dir = join(root, "no-manifest");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "mcp.json"), VALID_MANIFEST);
+
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: root,
+    });
+    expect(servers).toEqual([]);
+    expect(issues[0].message).toContain("package.json");
+  });
+
+  test("ignores a directory whose package.json is unparseable", () => {
+    const dir = makePluginsDir({
+      broken: { mcpJson: VALID_MANIFEST, packageJson: "{ not json" },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+    expect(servers).toEqual([]);
+    expect(issues[0].message).toContain("package.json");
+  });
+
+  test("ignores a directory whose package.json has no name", () => {
+    const dir = makePluginsDir({
+      nameless: {
+        mcpJson: VALID_MANIFEST,
+        packageJson: JSON.stringify({ version: "1.0.0" }),
+      },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+    expect(servers).toEqual([]);
+    expect(issues[0].message).toContain("package.json");
+  });
+
+  test("skips plugins with no mcp.json without complaining", () => {
+    const dir = makePluginsDir({ plain: {} });
+    expect(readPluginMcpServers({ workspacePluginsDir: dir })).toEqual({
+      servers: [],
+      issues: [],
+    });
+  });
+
+  test("skips disabled plugins entirely", () => {
+    const dir = makePluginsDir({
+      unabyss: { mcpJson: VALID_MANIFEST, disabled: true },
+    });
+    const { servers } = readPluginMcpServers({ workspacePluginsDir: dir });
+    expect(servers).toEqual([]);
+  });
+
+  test("an unparseable manifest disables only that plugin", () => {
+    const dir = makePluginsDir({
+      broken: { mcpJson: "{ not json" },
+      good: { mcpJson: VALID_MANIFEST },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+
+    expect(servers.map((s) => s.pluginName)).toEqual(["good"]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].pluginName).toEqual("broken");
+    expect(issues[0].message).toContain("invalid JSON");
+  });
+
+  test("a manifest missing mcpServers disables only that plugin", () => {
+    const dir = makePluginsDir({
+      broken: { mcpJson: JSON.stringify({ $schema: "x" }) },
+      good: { mcpJson: VALID_MANIFEST },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+
+    expect(servers.map((s) => s.pluginName)).toEqual(["good"]);
+    expect(issues[0].message).toContain("mcpServers");
+  });
+
+  test("an invalid entry disables only that entry, not its siblings", () => {
+    const dir = makePluginsDir({
+      acme: {
+        mcpJson: JSON.stringify({
+          mcpServers: {
+            good: { type: "streamable-http", url: "https://a.example" },
+            bad: { type: "streamable-http" },
+            alsoBad: { type: "carrier-pigeon", url: "https://b.example" },
+          },
+        }),
+      },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+
+    expect(servers.map((s) => s.serverKey)).toEqual(["good"]);
+    expect(issues.map((i) => i.serverKey).sort()).toEqual(["alsoBad", "bad"]);
+  });
+
+  test("projects a stdio server and expands its path variables", () => {
+    const dir = makePluginsDir({
+      local: {
+        mcpJson: JSON.stringify({
+          mcpServers: {
+            local: {
+              type: "stdio",
+              command: "node",
+              args: ["${PLUGIN_ROOT}/server.js"],
+              env: { STATE: "${PLUGIN_DATA}/state" },
+            },
+          },
+        }),
+      },
+    });
+    const { servers } = readPluginMcpServers({ workspacePluginsDir: dir });
+
+    const transport = servers[0].config.transport;
+    expect(transport.type).toEqual("stdio");
+    if (transport.type !== "stdio") {
+      throw new Error("expected a stdio transport");
+    }
+    expect(transport.command).toEqual("node");
+    expect(transport.args[0]).toEqual(join(dir, "local", "server.js"));
+    expect(transport.env?.STATE).toEqual(join(dir, "local", "data", "state"));
+  });
+
+  test("reports an ignored cwd rather than dropping it silently", () => {
+    const dir = makePluginsDir({
+      local: {
+        mcpJson: JSON.stringify({
+          mcpServers: {
+            local: { type: "stdio", command: "node", cwd: "${PLUGIN_ROOT}" },
+          },
+        }),
+      },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+
+    expect(servers).toHaveLength(1);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain("cwd");
+  });
+
+  test("two plugins claiming one id keep the first and report the second", () => {
+    // Both would otherwise register as `shared`, and whichever lost would
+    // simply be missing with no explanation.
+    const manifest = JSON.stringify({
+      mcpServers: { shared: { type: "sse", url: "https://s.example" } },
+    });
+    const dir = makePluginsDir({
+      "a-plugin": { mcpJson: manifest },
+      "b-plugin": { mcpJson: manifest },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+
+    expect(servers).toHaveLength(2);
+    expect(servers.map((s) => s.id).sort()).toEqual([
+      "a-plugin__shared",
+      "b-plugin__shared",
+    ]);
+    expect(issues).toEqual([]);
+  });
+
+  test("an id collision between two plugins keeps one and reports the other", () => {
+    // The id-collapsing rule makes this reachable: plugin `a` with key `b`
+    // qualifies to `a__b`, and plugin `a__b` with key `a__b` collapses to
+    // `a__b` too. Whichever loses would otherwise be silently missing.
+    const dir = makePluginsDir({
+      a: {
+        mcpJson: JSON.stringify({
+          mcpServers: { b: { type: "sse", url: "https://a.example" } },
+        }),
+      },
+      a__b: {
+        mcpJson: JSON.stringify({
+          mcpServers: { a__b: { type: "sse", url: "https://b.example" } },
+        }),
+      },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+
+    expect(servers.filter((s) => s.id === "a__b")).toHaveLength(1);
+    expect(issues.some((i) => i.message.includes("already declared"))).toBe(
+      true,
+    );
+  });
+
+  test("an empty server key is rejected rather than producing a nameless id", () => {
+    const dir = makePluginsDir({
+      acme: {
+        mcpJson: JSON.stringify({
+          mcpServers: { "": { type: "sse", url: "https://a.example" } },
+        }),
+      },
+    });
+    const { servers, issues } = readPluginMcpServers({
+      workspacePluginsDir: dir,
+    });
+
+    expect(servers).toEqual([]);
+    expect(issues[0].message).toContain("non-empty");
+  });
+
+  test("returns empty when the plugins directory does not exist", () => {
+    expect(
+      readPluginMcpServers({
+        workspacePluginsDir: join(tmpdir(), "vellum-does-not-exist-12345"),
+      }),
+    ).toEqual({ servers: [], issues: [] });
+  });
+});

package/src/plugins/defaults/memory/AGENTS.md

@@ -59,6 +59,10 @@ Everything else under the plugin root is **spine**:
 - Shared infra at the root: `logging`, `paths`, `embeddings`, `anisotropy`,
   `frontmatter`, `validation`, `llm-helpers`, `config`, `memory-db`,
   `host-utils`, `path-containment`, `prompt-override`, `memory-marker`,
+  `buffer-format` (the sole owner of the `memory/buffer.md` entry format:
+  the writer plus the one matcher every reader uses. It lives at the root
+  precisely so `substrate/`, `graph/`, and `graph-topology/` can all reach it
+  without a tier importing spine. Do not add a second matcher anywhere),
   `segmenter`, `message-media`, `worker`, `worker-control`,
   `memory-recall-log-store`, `activation-session-store` (the onboarding
   activation rail — **not** a memory tier despite the name),

package/src/plugins/defaults/memory/__tests__/buffer-format.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Tests for the single owner of the `memory/buffer.md` entry format.
+ *
+ * These cases pin exactly which lines count as an entry opening, covering the
+ * shapes a second matcher is most likely to get wrong: indentation, spacing
+ * after the bullet dash, and spacing inside the date. Every one of them is the
+ * difference between one fact and two.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  formatBufferTimestamp,
+  formatRememberEntry,
+  isBufferEntryStart,
+  matchBufferEntryStart,
+  splitBufferEntries,
+} from "../buffer-format.js";
+
+describe("matchBufferEntryStart", () => {
+  test("matches what formatRememberEntry writes, and captures both halves", () => {
+    const line = formatRememberEntry(
+      "Alice prefers dark mode",
+      new Date(2026, 0, 1, 9, 0),
+    ).trimEnd();
+    expect(line).toBe("- [Jan 1, 9:00 AM] Alice prefers dark mode");
+
+    const match = matchBufferEntryStart(line);
+    expect(match).toEqual({
+      timestamp: "Jan 1, 9:00 AM",
+      text: "Alice prefers dark mode",
+    });
+  });
+
+  test("round-trips every hour so the AM/PM and 12-hour edges hold", () => {
+    for (let hour = 0; hour < 24; hour++) {
+      const line = formatRememberEntry(
+        "fact",
+        new Date(2026, 0, 1, hour, 5),
+      ).trimEnd();
+      const match = matchBufferEntryStart(line);
+      expect(match).not.toBeNull();
+      expect(match!.timestamp).toBe(
+        formatBufferTimestamp(new Date(2026, 0, 1, hour, 5)),
+      );
+      expect(match!.text).toBe("fact");
+    }
+  });
+
+  test("an indented entry-shaped line is body text, not a new entry", () => {
+    // The writer puts only an entry's opening line at column 0 and nests the
+    // body under it, so anything indented is part of the fact above it.
+    // Reading it as an entry splits one fact into two nodes in the Memory tab.
+    expect(isBufferEntryStart("  - [Jan 1, 9:00 AM] indented")).toBe(false);
+    expect(isBufferEntryStart("\t- [Jan 1, 9:00 AM] tab-indented")).toBe(false);
+  });
+
+  test("only the writer's exact spacing counts as an entry", () => {
+    // A line the writer could not have produced is body text. Recognizing it
+    // would either split the fact holding it or hand a caller a timestamp in a
+    // shape that no real entry uses, which matters because the consolidation
+    // cutoff is compared against entry timestamps textually.
+    expect(isBufferEntryStart("-[Jan 1, 9:00 AM] no space after dash")).toBe(
+      false,
+    );
+    expect(isBufferEntryStart("-  [Jan 1, 9:00 AM] two spaces")).toBe(false);
+    expect(isBufferEntryStart("- [Jan  1, 9:00 AM] double-spaced date")).toBe(
+      false,
+    );
+    expect(
+      isBufferEntryStart("- [Jan 1, 9:00AM] no space before meridiem"),
+    ).toBe(false);
+  });
+
+  test("day and month widths the writer produces all match", () => {
+    // `formatBufferTimestamp` pads neither the day nor the hour, so single and
+    // double digit forms both occur on disk.
+    for (const line of [
+      "- [Jan 1, 9:00 AM] single-digit day and hour",
+      "- [Dec 31, 12:05 PM] double-digit day and hour",
+      "- [Sep 9, 11:59 PM] boundary",
+    ]) {
+      expect(isBufferEntryStart(line)).toBe(true);
+    }
+  });
+
+  test("continuation bullets carrying other bracketed text are not entries", () => {
+    expect(isBufferEntryStart("  - [ ] a checklist item")).toBe(false);
+    expect(isBufferEntryStart("- [ ] a checklist item")).toBe(false);
+    expect(isBufferEntryStart("- [[wikilink]] bullet")).toBe(false);
+    expect(isBufferEntryStart("  plain prose")).toBe(false);
+    expect(isBufferEntryStart("")).toBe(false);
+  });
+
+  test("tolerates trailing whitespace, which editors add invisibly", () => {
+    expect(isBufferEntryStart("- [Jan 1, 9:00 AM] fact   ")).toBe(true);
+  });
+});
+
+describe("formatRememberEntry round trip", () => {
+  const WRITTEN_AT = new Date(2026, 0, 1, 9, 0);
+
+  test("a fact whose body is itself entry-shaped survives as one entry", () => {
+    const content = "plan:\n- [Jan 2, 9:00 AM] step";
+    const written = formatRememberEntry(content, WRITTEN_AT);
+
+    // The body is nested, so it cannot be mistaken for the next fact.
+    expect(written).toBe(
+      "- [Jan 1, 9:00 AM] plan:\n  - [Jan 2, 9:00 AM] step\n",
+    );
+    expect(splitBufferEntries(written.trimEnd().split("\n"))).toHaveLength(1);
+  });
+
+  test("any content round-trips to exactly one entry", () => {
+    // The delimiter is "canonical entry shape at column 0", so the property
+    // that matters is that no fact body can imitate one, whatever the user
+    // dictated.
+    const adversarial = [
+      "plan:\n- [Jan 2, 9:00 AM] step",
+      "plan:\n- [Jan 2, 9:00 AM] step\n- [Jan 3, 10:15 PM] another",
+      "- [Jan 2, 9:00 AM] body opens with an entry shape",
+      "top\n\n- [Dec 31, 12:05 PM] after a blank line",
+      "top\n  - [Jan 2, 9:00 AM] already indented",
+      "top\n\t- [Jan 2, 9:00 AM] tab indented",
+      "top\n- [ ] checklist\n- [[wikilink]] doc\n- plain bullet",
+      "single line, no body",
+    ];
+
+    for (const content of adversarial) {
+      const written = formatRememberEntry(content, WRITTEN_AT);
+      expect(splitBufferEntries(written.trimEnd().split("\n"))).toHaveLength(1);
+    }
+  });
+
+  test("the fact text a reader recovers is unchanged by nesting", () => {
+    const content = "plan:\n- [Jan 2, 9:00 AM] step";
+    const groups = splitBufferEntries(
+      formatRememberEntry(content, WRITTEN_AT).trimEnd().split("\n"),
+    );
+    // Opening clause on the entry, body carried verbatim under it.
+    expect(groups[0]!.start?.text).toBe("plan:");
+    expect(groups[0]!.lines).toEqual([
+      "- [Jan 1, 9:00 AM] plan:",
+      "  - [Jan 2, 9:00 AM] step",
+    ]);
+  });
+
+  test("blank body lines stay blank rather than becoming whitespace", () => {
+    const written = formatRememberEntry("a\n\nb", WRITTEN_AT);
+    expect(written).toBe("- [Jan 1, 9:00 AM] a\n\n  b\n");
+  });
+});
+
+describe("splitBufferEntries", () => {
+  test("keeps a multiline fact's body with its opening line", () => {
+    const groups = splitBufferEntries([
+      "- [Jan 1, 9:00 AM] first",
+      "- [Jan 2, 9:00 AM] second",
+      "  body of second",
+      "  - [ ] checklist inside second",
+      "  - [Jan 3, 9:00 AM] indented, still second",
+    ]);
+
+    expect(groups).toHaveLength(2);
+    expect(groups[0]!.lines).toEqual(["- [Jan 1, 9:00 AM] first"]);
+    expect(groups[1]!.lines).toHaveLength(4);
+    expect(groups[1]!.start?.text).toBe("second");
+    expect(groups[1]!.firstLine).toBe(1);
+  });
+
+  test("surfaces leading prose as a headless group rather than dropping it", () => {
+    const groups = splitBufferEntries([
+      "hand-written header",
+      "- [Jan 1, 9:00 AM] first",
+    ]);
+
+    expect(groups).toHaveLength(2);
+    expect(groups[0]!.start).toBeNull();
+    expect(groups[0]!.lines).toEqual(["hand-written header"]);
+    expect(groups[1]!.start).not.toBeNull();
+  });
+
+  test("a buffer with no entries at all is one headless group", () => {
+    const groups = splitBufferEntries(["just prose", "more prose"]);
+    expect(groups).toHaveLength(1);
+    expect(groups[0]!.start).toBeNull();
+    expect(groups[0]!.lines).toHaveLength(2);
+  });
+
+  test("preserves every input line exactly once, in order", () => {
+    const lines = [
+      "prose",
+      "- [Jan 1, 9:00 AM] a",
+      "  body",
+      "",
+      "- [Jan 2, 9:00 AM] b",
+    ];
+    expect(splitBufferEntries(lines).flatMap((g) => g.lines)).toEqual(lines);
+  });
+
+  test("empty input yields no groups", () => {
+    expect(splitBufferEntries([])).toEqual([]);
+  });
+});

package/src/plugins/defaults/memory/__tests__/memory-retrospective-accounting.test.ts

@@ -1,5 +1,7 @@
 import { beforeEach, describe, expect, test } from "bun:test";
 
+import { eq } from "drizzle-orm";
+
 import {
   createConversation,
   type MessageRow,
@@ -8,6 +10,7 @@ import { getDb } from "../../../../persistence/db-connection.js";
 import { initializeDb } from "../../../../persistence/db-init.js";
 import { messages } from "../../../../persistence/schema/index.js";
 import {
+  getRetrospectiveMessagesAfter,
   hasQualifyingUserMessageAfter,
   messagesHaveUserActivity,
 } from "../memory-retrospective-accounting.js";
@@ -197,3 +200,72 @@ describe("messagesHaveUserActivity", () => {
     expect(messagesHaveUserActivity([])).toBe(false);
   });
 });
+
+describe("getRetrospectiveMessagesAfter", () => {
+  beforeEach(() => {
+    const db = getDb();
+    db.run(`DELETE FROM messages`);
+    db.run(`DELETE FROM conversations`);
+    createConversation({ id: CONV });
+  });
+
+  test("truncates at a stale mid-slice unfinalized row so the cursor never passes it", () => {
+    const first = insertRaw({ role: "user", content: TEXT, createdAt: 1_000 });
+    const stale = insertRaw({
+      role: "assistant",
+      content: TEXT,
+      createdAt: 2_000,
+    });
+    insertRaw({ role: "user", content: TEXT, createdAt: 3_000 });
+    insertRaw({ role: "assistant", content: TEXT, createdAt: 4_000 });
+    getDb()
+      .update(messages)
+      .set({ finalized: 0 })
+      .where(eq(messages.id, stale))
+      .run();
+
+    const slice = getRetrospectiveMessagesAfter(CONV, null);
+
+    // The slice stops BEFORE the stale row: taking the later finalized rows
+    // as the cutoff would advance the cursor past the stale row, and once it
+    // finalizes it would sit behind the cursor, unreviewed forever.
+    expect(slice.map((row) => row.id)).toEqual([first]);
+
+    getDb()
+      .update(messages)
+      .set({ finalized: 1 })
+      .where(eq(messages.id, stale))
+      .run();
+
+    // Once the row resolves, the slice continues past it.
+    expect(getRetrospectiveMessagesAfter(CONV, null)).toHaveLength(4);
+  });
+
+  test("excludes unfinalized rows so the cutoff stays on rows a fork holds", () => {
+    insertRaw({ role: "user", content: TEXT, createdAt: 1_000 });
+    const lastFinalized = insertRaw({
+      role: "assistant",
+      content: TEXT,
+      createdAt: 2_000,
+    });
+    const streaming = insertRaw({
+      role: "assistant",
+      content: TEXT,
+      createdAt: 3_000,
+    });
+    getDb()
+      .update(messages)
+      .set({ finalized: 0 })
+      .where(eq(messages.id, streaming))
+      .run();
+
+    const slice = getRetrospectiveMessagesAfter(CONV, null);
+
+    // The invariant: no slice member is unfinalized, and the cutoff the job
+    // would take (the last slice row) is a row the retrospective fork
+    // actually contains.
+    expect(slice.some((row) => row.finalized === 0)).toBe(false);
+    expect(slice.at(-1)?.id).toBe(lastFinalized);
+    expect(slice.map((row) => row.id)).not.toContain(streaming);
+  });
+});

package/src/plugins/defaults/memory/__tests__/memory-retrospective-job.test.ts

@@ -168,7 +168,10 @@ mock.module("../find-most-recent-retrospective-for.js", () => ({
 mock.module("../../../../persistence/conversation-crud.js", () => ({
   getMessagesAfter: (id: string, afterId: string | null) => {
     messagesAfterCalls.push({ conversationId: id, afterId });
-    return newMessages;
+    // Real rows always carry `finalized` (NOT NULL, default 1); the slice
+    // filter drops unfinalized rows, so mock rows default to finalized
+    // unless a test explicitly stages a streaming row.
+    return newMessages.map((row) => ({ finalized: 1, ...row }));
   },
   getMessages: (id: string) => {
     if (messagesByConversationId[id]) {