@vellumai/assistant 0.8.12 → 0.9.0-staging.2

package/src/memory/__tests__/memory-retrospective-startup-cleanup.test.ts

@@ -23,11 +23,23 @@ type JobRow = {
   status: string;
   payload: string;
 };
+type MessageRow = {
+  role: string;
+  createdAt: number;
+  metadata: string | null;
+};
 
 let mockConversations: ConvRow[] = [];
 let mockJobs: JobRow[] = [];
+let mockMessages: Record<string, MessageRow[]> = {};
 let deletedIds: string[] = [];
 
+const RETRO_SOURCES = ["memory-retrospective", "memory-retrospective-fork"];
+
+function isRetroSource(source: string | null): boolean {
+  return source !== null && RETRO_SOURCES.includes(source);
+}
+
 mock.module("../db-connection.js", () => ({
   getDb: () => ({
     select: (cols?: Record<string, unknown>) => ({
@@ -60,18 +72,20 @@ mock.module("../db-connection.js", () => ({
                   return { conversationId: convId };
                 });
             }
-            // The "all retros" query (used to compute most-recent-per-source
-            // preservation) requests id + forkParentConversationId + createdAt
-            // with only the source + isNotNull(forkParent) predicate.
+            // The "all retros" query (used to compute the preserved
+            // dedup-baseline per source) requests id + source +
+            // forkParentConversationId + createdAt with only the source +
+            // isNotNull(forkParent) predicate.
             if (
               colKeys.includes("forkParentConversationId") &&
               colKeys.includes("createdAt")
             ) {
               return mockConversations
-                .filter((c) => c.source === "memory-retrospective")
+                .filter((c) => isRetroSource(c.source))
                 .filter((c) => c.fork_parent_conversation_id !== null)
                 .map((c) => ({
                   id: c.id,
+                  source: c.source,
                   forkParentConversationId: c.fork_parent_conversation_id,
                   createdAt: c.created_at,
                 }));
@@ -81,7 +95,7 @@ mock.module("../db-connection.js", () => ({
             // encoded on the background conversation row) against the set
             // of source IDs extracted from active jobs.
             return mockConversations
-              .filter((c) => c.source === "memory-retrospective")
+              .filter((c) => isRetroSource(c.source))
               .filter(
                 (c) =>
                   c.last_message_at !== null &&
@@ -102,12 +116,22 @@ mock.module("../db-connection.js", () => ({
 
 let activeJobSourceConvIds = new Set<string>();
 let injectedNowMinusOrphanAgeMs = 0;
+let mockKeepSupersededRuns = false;
+
+mock.module("../../config/loader.js", () => ({
+  getConfig: () => ({
+    memory: {
+      retrospective: { keepSupersededRuns: mockKeepSupersededRuns },
+    },
+  }),
+}));
 
 mock.module("../conversation-crud.js", () => ({
   deleteConversation: (id: string) => {
     deletedIds.push(id);
     mockConversations = mockConversations.filter((c) => c.id !== id);
   },
+  getMessages: (conversationId: string) => mockMessages[conversationId] ?? [],
   reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
@@ -139,14 +163,17 @@ describe("sweepOrphanMemoryRetrospectiveConversations", () => {
   beforeEach(() => {
     mockConversations = [];
     mockJobs = [];
+    mockMessages = {};
     deletedIds = [];
     activeJobSourceConvIds = new Set();
     injectedNowMinusOrphanAgeMs = 0;
+    mockKeepSupersededRuns = false;
   });
 
   afterEach(() => {
     mockConversations = [];
     mockJobs = [];
+    mockMessages = {};
   });
 
   test("sweeps an old memory-retrospective orphan that has been superseded by a newer retro for the same source", () => {
@@ -316,4 +343,199 @@ describe("sweepOrphanMemoryRetrospectiveConversations", () => {
     expect(result.swept).toBe(0);
     expect(deletedIds).toEqual([]);
   });
+
+  test("keepSupersededRuns=true skips the sweep entirely — sweepable orphans are retained", () => {
+    mockKeepSupersededRuns = true;
+    const now = Date.now();
+    injectedNowMinusOrphanAgeMs = now - ORPHAN_AGE_MS;
+    // Same shape as the first test's sweepable orphan — with the flag off
+    // this would be swept (older retro superseded by a newer one for the
+    // same source).
+    mockConversations = [
+      {
+        id: "old-orphan",
+        source: "memory-retrospective",
+        last_message_at: now - 2 * ORPHAN_AGE_MS,
+        fork_parent_conversation_id: "source-A",
+        created_at: now - 3 * ORPHAN_AGE_MS,
+      },
+      {
+        id: "newer-retro",
+        source: "memory-retrospective",
+        last_message_at: now - 90 * 60 * 1000,
+        fork_parent_conversation_id: "source-A",
+        created_at: now - 2 * ORPHAN_AGE_MS,
+      },
+    ];
+    rebuildActiveJobSet();
+
+    const result = sweepOrphanMemoryRetrospectiveConversations(now);
+
+    expect(result.swept).toBe(0);
+    expect(deletedIds).toEqual([]);
+  });
+
+  // -------------------------------------------------------------------------
+  // Dedup-baseline selection: prefer rows that actually produced output.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Build a fork-kind retrospective's message rows: a copied source prefix
+   * (stamped with `forkSourceMessageId`, ending in an assistant turn AT the
+   * boundary — exercising the strictly-greater check), the post-fork
+   * user-role instruction, and optionally the retrospective's own assistant
+   * output after the boundary.
+   */
+  function forkKindMessages(opts: {
+    boundaryAt: number;
+    withOutput: boolean;
+  }): MessageRow[] {
+    const rows: MessageRow[] = [
+      {
+        role: "user",
+        createdAt: opts.boundaryAt - 1000,
+        metadata: JSON.stringify({ forkSourceMessageId: "src-msg-1" }),
+      },
+      {
+        role: "assistant",
+        createdAt: opts.boundaryAt,
+        metadata: JSON.stringify({ forkSourceMessageId: "src-msg-2" }),
+      },
+      {
+        role: "user",
+        createdAt: opts.boundaryAt + 500,
+        metadata: JSON.stringify({ kind: "memory_retrospective_instruction" }),
+      },
+    ];
+    if (opts.withOutput) {
+      rows.push({
+        role: "assistant",
+        createdAt: opts.boundaryAt + 1000,
+        metadata: null,
+      });
+    }
+    return rows;
+  }
+
+  test("sweeps an orphan MOST-RECENT fork-kind row (no post-fork output) and preserves an older row WITH output as the dedup baseline", () => {
+    const now = Date.now();
+    injectedNowMinusOrphanAgeMs = now - ORPHAN_AGE_MS;
+    mockConversations = [
+      {
+        id: "fork-with-output",
+        source: "memory-retrospective-fork",
+        last_message_at: now - 3 * ORPHAN_AGE_MS,
+        fork_parent_conversation_id: "source-A",
+        created_at: now - 3 * ORPHAN_AGE_MS,
+      },
+      // Most recent for source-A, but a crash orphan: its only post-fork
+      // message is the instruction — no assistant output after the boundary.
+      // The copied prefix DOES contain an assistant turn (at the boundary),
+      // which must not count.
+      {
+        id: "fork-orphan",
+        source: "memory-retrospective-fork",
+        last_message_at: now - 2 * ORPHAN_AGE_MS,
+        fork_parent_conversation_id: "source-A",
+        created_at: now - 2 * ORPHAN_AGE_MS,
+      },
+    ];
+    mockMessages = {
+      "fork-with-output": forkKindMessages({
+        boundaryAt: now - 3 * ORPHAN_AGE_MS,
+        withOutput: true,
+      }),
+      "fork-orphan": forkKindMessages({
+        boundaryAt: now - 2 * ORPHAN_AGE_MS,
+        withOutput: false,
+      }),
+    };
+    rebuildActiveJobSet();
+
+    const result = sweepOrphanMemoryRetrospectiveConversations(now);
+
+    expect(result.swept).toBe(1);
+    expect(deletedIds).toEqual(["fork-orphan"]);
+  });
+
+  test("falls back to preserving the plain most-recent row when EVERY row is an orphan", () => {
+    const now = Date.now();
+    injectedNowMinusOrphanAgeMs = now - ORPHAN_AGE_MS;
+    mockConversations = [
+      {
+        id: "older-orphan",
+        source: "memory-retrospective-fork",
+        last_message_at: now - 3 * ORPHAN_AGE_MS,
+        fork_parent_conversation_id: "source-A",
+        created_at: now - 3 * ORPHAN_AGE_MS,
+      },
+      {
+        id: "newest-orphan",
+        source: "memory-retrospective-fork",
+        last_message_at: now - 2 * ORPHAN_AGE_MS,
+        fork_parent_conversation_id: "source-A",
+        created_at: now - 2 * ORPHAN_AGE_MS,
+      },
+    ];
+    mockMessages = {
+      "older-orphan": forkKindMessages({
+        boundaryAt: now - 3 * ORPHAN_AGE_MS,
+        withOutput: false,
+      }),
+      "newest-orphan": forkKindMessages({
+        boundaryAt: now - 2 * ORPHAN_AGE_MS,
+        withOutput: false,
+      }),
+    };
+    rebuildActiveJobSet();
+
+    const result = sweepOrphanMemoryRetrospectiveConversations(now);
+
+    // Current behavior preserved: the most-recent row survives even though
+    // it has no output; the older orphan is swept.
+    expect(result.swept).toBe(1);
+    expect(deletedIds).toEqual(["older-orphan"]);
+  });
+
+  test("legacy-kind selection: ANY assistant message counts as output (no fork boundary required)", () => {
+    const now = Date.now();
+    injectedNowMinusOrphanAgeMs = now - ORPHAN_AGE_MS;
+    mockConversations = [
+      // Older legacy retro that produced output — preserved.
+      {
+        id: "legacy-with-output",
+        source: "memory-retrospective",
+        last_message_at: now - 3 * ORPHAN_AGE_MS,
+        fork_parent_conversation_id: "source-A",
+        created_at: now - 3 * ORPHAN_AGE_MS,
+      },
+      // Most-recent legacy retro with no assistant message — a wake that
+      // never produced output. Swept.
+      {
+        id: "legacy-orphan",
+        source: "memory-retrospective",
+        last_message_at: now - 2 * ORPHAN_AGE_MS,
+        fork_parent_conversation_id: "source-A",
+        created_at: now - 2 * ORPHAN_AGE_MS,
+      },
+    ];
+    mockMessages = {
+      "legacy-with-output": [
+        // Legacy rows carry no forkSourceMessageId stamps — any assistant
+        // message qualifies.
+        {
+          role: "assistant",
+          createdAt: now - 3 * ORPHAN_AGE_MS,
+          metadata: null,
+        },
+      ],
+      "legacy-orphan": [],
+    };
+    rebuildActiveJobSet();
+
+    const result = sweepOrphanMemoryRetrospectiveConversations(now);
+
+    expect(result.swept).toBe(1);
+    expect(deletedIds).toEqual(["legacy-orphan"]);
+  });
 });

package/src/memory/__tests__/memory-retrospective-state.test.ts

@@ -0,0 +1,195 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { eq } from "drizzle-orm";
+
+import { makeMockLogger } from "../../__tests__/helpers/mock-logger.js";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () => makeMockLogger(),
+}));
+
+mock.module("../../config/loader.js", () => ({
+  getConfig: () => ({
+    ui: {},
+    model: "test",
+    provider: "test",
+    memory: { enabled: false },
+    rateLimit: { maxRequestsPerMinute: 0 },
+    secretDetection: { enabled: false },
+  }),
+}));
+
+import { createConversation } from "../conversation-crud.js";
+import { getDb } from "../db-connection.js";
+import { initializeDb } from "../db-init.js";
+import {
+  appendToRememberedLog,
+  bumpRetrospectiveLastRunAt,
+  forkRetrospectiveState,
+  getRetrospectiveState,
+  REMEMBERED_LOG_MAX_BYTES,
+  REMEMBERED_LOG_MAX_ENTRIES,
+  upsertRetrospectiveState,
+} from "../memory-retrospective-state.js";
+import { memoryRetrospectiveState } from "../schema.js";
+
+initializeDb();
+
+function resetTables(): void {
+  const db = getDb();
+  db.delete(memoryRetrospectiveState).run();
+  db.run("DELETE FROM messages");
+  db.run("DELETE FROM conversations");
+}
+
+describe("appendToRememberedLog", () => {
+  test("appends new entries after existing ones, order preserved", () => {
+    expect(appendToRememberedLog(["a", "b"], ["c"])).toEqual(["a", "b", "c"]);
+    expect(appendToRememberedLog([], ["x"])).toEqual(["x"]);
+    expect(appendToRememberedLog(["x"], [])).toEqual(["x"]);
+  });
+
+  test("entry cap keeps the most recent entries", () => {
+    const existing = Array.from({ length: 99 }, (_, i) => `old-${i}`);
+    const result = appendToRememberedLog(existing, ["new-1", "new-2", "new-3"]);
+
+    expect(result).toHaveLength(REMEMBERED_LOG_MAX_ENTRIES);
+    // Oldest entries dropped first.
+    expect(result[0]).toBe("old-2");
+    expect(result.at(-1)).toBe("new-3");
+  });
+
+  test("byte cap binds before the entry cap when entries are large", () => {
+    // 20 entries of ~1 KB each — well under the entry cap but over 8 KB.
+    const entries = Array.from(
+      { length: 20 },
+      (_, i) => `${i}-${"x".repeat(1024)}`,
+    );
+    const result = appendToRememberedLog([], entries);
+
+    expect(result.length).toBeLessThan(entries.length);
+    expect(result.length).toBeGreaterThan(0);
+    expect(
+      Buffer.byteLength(JSON.stringify(result), "utf8"),
+    ).toBeLessThanOrEqual(REMEMBERED_LOG_MAX_BYTES);
+    // Most recent entries survive.
+    expect(result.at(-1)).toBe(entries.at(-1));
+  });
+
+  test("a single entry larger than the byte cap yields an empty log", () => {
+    const huge = "y".repeat(REMEMBERED_LOG_MAX_BYTES + 1);
+    expect(appendToRememberedLog([], [huge])).toEqual([]);
+  });
+});
+
+describe("memory-retrospective-state remembered log persistence", () => {
+  beforeEach(() => {
+    resetTables();
+  });
+
+  test("upsert persists the log and getRetrospectiveState parses it back", () => {
+    const conv = createConversation("Log thread");
+    upsertRetrospectiveState({
+      conversationId: conv.id,
+      lastProcessedMessageId: "m1",
+      lastRunAt: 1000,
+      rememberedLog: ["save one", "save two"],
+    });
+
+    const state = getRetrospectiveState(conv.id);
+    expect(state?.rememberedLog).toEqual(["save one", "save two"]);
+    expect(state?.lastProcessedMessageId).toBe("m1");
+  });
+
+  test("upsert without rememberedLog preserves the stored log", () => {
+    const conv = createConversation("Preserve thread");
+    upsertRetrospectiveState({
+      conversationId: conv.id,
+      lastProcessedMessageId: "m1",
+      lastRunAt: 1000,
+      rememberedLog: ["keep me"],
+    });
+    upsertRetrospectiveState({
+      conversationId: conv.id,
+      lastProcessedMessageId: "m2",
+      lastRunAt: 2000,
+    });
+
+    const state = getRetrospectiveState(conv.id);
+    expect(state?.lastProcessedMessageId).toBe("m2");
+    expect(state?.rememberedLog).toEqual(["keep me"]);
+  });
+
+  test("missing/NULL column value parses as an empty log", () => {
+    const conv = createConversation("Null-log thread");
+    upsertRetrospectiveState({
+      conversationId: conv.id,
+      lastProcessedMessageId: "m1",
+      lastRunAt: 1000,
+    });
+
+    expect(getRetrospectiveState(conv.id)?.rememberedLog).toEqual([]);
+  });
+
+  test("malformed stored JSON degrades to an empty log instead of throwing", () => {
+    const conv = createConversation("Corrupt thread");
+    upsertRetrospectiveState({
+      conversationId: conv.id,
+      lastProcessedMessageId: "m1",
+      lastRunAt: 1000,
+      rememberedLog: ["x"],
+    });
+    getDb()
+      .update(memoryRetrospectiveState)
+      .set({ rememberedLog: "not-json{{" })
+      .where(eq(memoryRetrospectiveState.conversationId, conv.id))
+      .run();
+
+    expect(getRetrospectiveState(conv.id)?.rememberedLog).toEqual([]);
+  });
+
+  test("bumpRetrospectiveLastRunAt seeds the empty-string sentinel with an empty log and preserves an existing log", () => {
+    // Failure-only row: "" sentinel, empty log.
+    const fresh = createConversation("Failure-only thread");
+    bumpRetrospectiveLastRunAt(fresh.id, 1000);
+    const freshState = getRetrospectiveState(fresh.id);
+    expect(freshState?.lastProcessedMessageId).toBe("");
+    expect(freshState?.rememberedLog).toEqual([]);
+
+    // Existing row with a log: a failure bump must not clobber it.
+    const seasoned = createConversation("Seasoned thread");
+    upsertRetrospectiveState({
+      conversationId: seasoned.id,
+      lastProcessedMessageId: "m1",
+      lastRunAt: 1000,
+      rememberedLog: ["survives failures"],
+    });
+    bumpRetrospectiveLastRunAt(seasoned.id, 2000);
+    const seasonedState = getRetrospectiveState(seasoned.id);
+    expect(seasonedState?.lastRunAt).toBe(2000);
+    expect(seasonedState?.rememberedLog).toEqual(["survives failures"]);
+  });
+
+  test("forkRetrospectiveState copies the log verbatim to the forked child", () => {
+    const source = createConversation("Fork source");
+    const child = createConversation("Fork child");
+    upsertRetrospectiveState({
+      conversationId: source.id,
+      lastProcessedMessageId: "",
+      lastRunAt: 1000,
+      rememberedLog: ["parent baseline"],
+    });
+
+    forkRetrospectiveState({
+      database: getDb(),
+      sourceConversationId: source.id,
+      forkedConversationId: child.id,
+      forkedMessageIds: new Map(),
+      lastCopiedSourceMessageId: null,
+    });
+
+    expect(getRetrospectiveState(child.id)?.rememberedLog).toEqual([
+      "parent baseline",
+    ]);
+  });
+});

package/src/memory/__tests__/preloaded-apps.test.ts

@@ -0,0 +1,85 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { setOverridesForTesting } from "../../__tests__/feature-flag-test-helpers.js";
+import type { AssistantConfig } from "../../config/schema.js";
+import { getAppsDir } from "../app-store.js";
+import {
+  ACTIVATION_FLOW_FLAG,
+  PERSONAL_PAGE_APP_ID,
+  PERSONAL_PAGE_ARM,
+  seedPreloadedApps,
+} from "../preloaded-apps.js";
+
+// The flag resolver reads the override cache and registry; the config
+// argument is part of the signature but not consulted for resolution.
+const config = {} as AssistantConfig;
+
+function definitionPath(): string {
+  return join(getAppsDir(), `${PERSONAL_PAGE_APP_ID}.json`);
+}
+
+function appDir(): string {
+  return join(getAppsDir(), PERSONAL_PAGE_APP_ID);
+}
+
+beforeEach(() => {
+  setOverridesForTesting({});
+});
+
+afterEach(() => {
+  setOverridesForTesting({});
+  rmSync(definitionPath(), { force: true });
+  rmSync(appDir(), { recursive: true, force: true });
+});
+
+describe("seedPreloadedApps gating", () => {
+  test("does not seed on the control arm", async () => {
+    setOverridesForTesting({ [ACTIVATION_FLOW_FLAG]: "control" });
+    await seedPreloadedApps(config);
+    expect(existsSync(definitionPath())).toBe(false);
+    expect(existsSync(appDir())).toBe(false);
+  });
+
+  test("does not seed on other treatment arms", async () => {
+    setOverridesForTesting({ [ACTIVATION_FLOW_FLAG]: "variant-a" });
+    await seedPreloadedApps(config);
+    expect(existsSync(definitionPath())).toBe(false);
+  });
+
+  test("does not seed when the flag resolves to the registry default", async () => {
+    // No override → declared default "control".
+    await seedPreloadedApps(config);
+    expect(existsSync(definitionPath())).toBe(false);
+  });
+
+  test("leaves an already-seeded, compiled app untouched", async () => {
+    setOverridesForTesting({ [ACTIVATION_FLOW_FLAG]: PERSONAL_PAGE_ARM });
+
+    const sentinelDefinition = JSON.stringify({
+      id: PERSONAL_PAGE_APP_ID,
+      userEdited: true,
+    });
+    mkdirSync(join(appDir(), "dist"), { recursive: true });
+    writeFileSync(definitionPath(), sentinelDefinition, "utf-8");
+    writeFileSync(
+      join(appDir(), "dist", "index.html"),
+      "<!-- compiled -->",
+      "utf-8",
+    );
+
+    await seedPreloadedApps(config);
+
+    // Seeding must not re-copy the template or rewrite the definition once
+    // the app exists — its content is considered user-owned.
+    expect(readFileSync(definitionPath(), "utf-8")).toBe(sentinelDefinition);
+    expect(existsSync(join(appDir(), "src"))).toBe(false);
+  });
+});

package/src/memory/auto-analysis-enqueue.ts

@@ -7,6 +7,7 @@ import {
 import { getLogger } from "../util/logger.js";
 import { isAutoAnalysisConversation } from "./auto-analysis-guard.js";
 import { isMemoryEnabled, upsertAutoAnalysisJob } from "./jobs-store.js";
+import { isMemoryRetrospectiveConversation } from "./memory-retrospective-enqueue.js";
 
 const log = getLogger("auto-analysis-enqueue");
 
@@ -31,7 +32,11 @@ export type AutoAnalysisTrigger = "batch" | "idle" | "lifecycle" | "compaction";
  * conversation. Skips silently when:
  *   - the `auto-analyze` feature flag is disabled, OR
  *   - the source conversation is itself an auto-analysis conversation
- *     (recursion guard — we never analyze our own analysis output).
+ *     (recursion guard — we never analyze our own analysis output), OR
+ *   - the source conversation is a memory-retrospective conversation.
+ *     Fork-kind retrospectives carry a full copy of the source
+ *     conversation's history, so auto-analyzing one would re-process the
+ *     entire source conversation and double-write memory.
  *
  * Immediate triggers (`"batch"`, `"compaction"`) and debounced triggers
  * (`"idle"`, `"lifecycle"`) are written to separate rows keyed by a
@@ -73,6 +78,14 @@ export function enqueueAutoAnalysisIfEnabled(args: {
     return;
   }
 
+  if (isMemoryRetrospectiveConversation(conversationId)) {
+    log.debug(
+      { conversationId, trigger },
+      "Skipping auto-analysis enqueue: source is a memory-retrospective conversation",
+    );
+    return;
+  }
+
   const idleTimeoutMs = config.analysis?.idleTimeoutMs ?? 600_000;
   const runImmediately = trigger === "batch" || trigger === "compaction";
   const triggerGroup: "immediate" | "debounced" = runImmediately

package/src/memory/compaction-log-store-clickhouse.ts

@@ -213,10 +213,12 @@ export class ClickHouseCompactionLogStore {
 
   /**
    * Read all compaction attempts whose `started_at` falls strictly inside
-   * the given window, pairing start/end rows by `compaction_id`. Mirrors
-   * the strict `>` / `<` predicate contract of
-   * `getCompactionLogsBetween` on the llm-request-log sources, so the
-   * route can apply the same ±1ms boundary shifts to both.
+   * the open window `(afterStartedAt, beforeStartedAt)`, pairing start/end
+   * rows by `compaction_id`. Mirrors the strict `>` / `<` predicate
+   * contract of `getCompactionLogsBetween` on the llm-request-log sources
+   * so the compaction route can scope both stores to the same call window
+   * (floor = previous real call's `createdAt`, ceiling = selected call's
+   * `createdAt`).
    */
   async getEventsBetween(
     conversationId: string,

package/src/memory/conversation-crud.ts

@@ -731,6 +731,13 @@ export function findAnalysisConversationFor(
  * Once the fork accumulates its own retros, those are found at the first
  * iteration and we never walk up.
  *
+ * The returned `forkParentConversationId` is the conversation the
+ * retrospective row is rooted at — `parentConversationId` itself when it has
+ * its own retros, or an ancestor when the chain walk found the row higher
+ * up. Callers that mutate the prior (e.g. GC of superseded runs) must check
+ * it against the source conversation: an ancestor's row is that ancestor's
+ * dedup baseline, not the caller's to delete.
+ *
  * Returns `null` when no prior retrospective exists anywhere in the fork
  * chain (true first-run case).
  *
@@ -741,7 +748,7 @@ const MAX_FORK_CHAIN_DEPTH = 16;
 
 export function findMostRecentRetrospectiveFor(
   parentConversationId: string,
-): { id: string } | null {
+): { id: string; forkParentConversationId: string } | null {
   const db = getDb();
   let currentId: string | null = parentConversationId;
   for (let depth = 0; depth < MAX_FORK_CHAIN_DEPTH && currentId; depth++) {
@@ -757,7 +764,7 @@ export function findMostRecentRetrospectiveFor(
       .orderBy(desc(conversations.createdAt))
       .limit(1)
       .get();
-    if (row) return { id: row.id };
+    if (row) return { id: row.id, forkParentConversationId: currentId };
 
     const parent = db
       .select({

package/src/memory/conversation-disk-view.ts

@@ -2,7 +2,7 @@
  * Write-through disk view for conversations.
  *
  * Projects conversation metadata, messages, and attachments to a browsable
- * filesystem layout under ~/.vellum/workspace/conversations/. This enables
+ * filesystem layout under $VELLUM_WORKSPACE_DIR/conversations/. This enables
  * the assistant to search/read/manipulate conversation data using standard
  * file tools.
  *