fix(sessions): align behavioral suites and flip proof with retained history, route-aware cleanup plans

steipete · steipete · commit 568ce44eba27 · 2026-07-19T03:31:39.000-07:00
diff --git a/src/config/sessions/session-accessor.conformance.test.ts b/src/config/sessions/session-accessor.conformance.test.ts
@@ -441,7 +441,12 @@ describe.each([publicAccessorAdapter, sqliteAdapter])(
           orphanTranscriptMinAgeMs: 300_000,
           nowMs,
         }),
-      ).resolves.toEqual({ removedEntries: 2, archivedTranscriptArtifacts: 2 });
+      ).resolves.toEqual({
+        // Only the removed entry's transcript is archived: the orphan's route
+        // row still targets it, and route-referenced history is retained.
+        removedEntries: 2,
+        archivedTranscriptArtifacts: 1,
+      });
 
       expect(
         adapter.loadSessionEntry(scopedEntry("agent:main:lifecycle-cleanup-missing")),
@@ -500,7 +505,11 @@ describe.each([publicAccessorAdapter, sqliteAdapter])(
           file.startsWith("orphan-lifecycle.jsonl.deleted."),
         );
         expect(removedArchive).toBeDefined();
-        expect(orphanArchive).toBeDefined();
+        // Route-referenced orphan history is retained in SQLite, not archived.
+        expect(orphanArchive).toBeUndefined();
+        await expect(
+          adapter.loadTranscriptEvents(scopedTranscript("agent:main:orphan", "orphan-lifecycle")),
+        ).resolves.not.toEqual([]);
         expect(
           readSessionArchiveContentSync(
             path.join(path.dirname(cleanupStorePath), removedArchive ?? ""),
@@ -1616,7 +1625,7 @@ describe("sqlite session normalization", () => {
     });
   });
 
-  it("evicts old SQLite transcript rows only when no remaining entry references them", async () => {
+  it("keeps live entries and transcripts under byte pressure at save time", async () => {
     vi.mocked(getRuntimeConfig).mockReturnValue({
       session: {
         maintenance: {
@@ -1697,6 +1706,9 @@ describe("sqlite session normalization", () => {
       modelOverride: "gpt-5.5",
     }));
 
+    // Live sessions are never save-time budget victims: byte pressure is
+    // handled by the async physical-budget pass, which only reclaims
+    // historical generations no entry, route, or admission references.
     expect(
       listSqliteSessionEntries({
         agentId: "main",
@@ -1705,7 +1717,7 @@ describe("sqlite session normalization", () => {
       })
         .map((summary) => summary.sessionKey)
         .toSorted(),
-    ).toEqual(["agent:main:active-budget"]);
+    ).toEqual(["agent:main:active-budget", "agent:main:old-budget", "agent:main:unshared-budget"]);
     await expect(
       loadSqliteTranscriptEvents({
         agentId: "main",
@@ -1725,18 +1737,14 @@ describe("sqlite session normalization", () => {
         sessionId: "unshared-budget-session",
         storePath: paths.sqlitePath,
       }),
-    ).resolves.toEqual([]);
-    const archivedOldBudget = fs
-      .readdirSync(paths.tempDir)
-      .filter((file) => file.startsWith("old-budget-session.jsonl.deleted."));
-    expect(archivedOldBudget).toHaveLength(0);
-    const archivedUnsharedBudget = fs
-      .readdirSync(paths.tempDir)
-      .filter((file) => file.startsWith("unshared-budget-session.jsonl.deleted."));
-    expect(archivedUnsharedBudget).toHaveLength(1);
+    ).resolves.toEqual([
+      expect.objectContaining({
+        id: "unshared-budget-event",
+      }),
+    ]);
     expect(
-      readSessionArchiveContentSync(path.join(paths.tempDir, archivedUnsharedBudget[0] ?? "")),
-    ).toContain("unshared-budget-event");
+      fs.readdirSync(paths.tempDir).filter((file) => file.includes(".jsonl.deleted.")),
+    ).toEqual([]);
   });
 
   it("resolves confirmed lowercased legacy SQLite session aliases", async () => {
diff --git a/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts b/src/config/sessions/session-accessor.sqlite-lifecycle-state.ts
@@ -419,6 +419,18 @@ export function collectProjectedReferencedSqliteSessionIds(params: {
   for (const sessionId of collectReferencedSqliteSessionIdsFromStore(params.projectedStore)) {
     sessionIds.add(sessionId);
   }
+  // Routes protect their target session unless the cleanup removes that key's
+  // route in the same pass; mirroring the post-cleanup state here keeps the
+  // plan from writing archives for sessions the delete stage will retain.
+  const routeRows = executeSqliteQuerySync(
+    params.database.db,
+    db.selectFrom("session_routes").select(["session_id", "session_key"]),
+  ).rows;
+  for (const row of routeRows) {
+    if (!excludedSessionKeys.has(row.session_key)) {
+      sessionIds.add(row.session_id);
+    }
+  }
   return sessionIds;
 }
 
diff --git a/src/config/sessions/session-history-eviction.test.ts b/src/config/sessions/session-history-eviction.test.ts
@@ -322,7 +322,9 @@ describe("kickSessionHistoryDiskBudgetMaintenance", () => {
     });
     // Give the fire-and-forget pass a tick to settle; an under-budget store
     // must leave every session untouched.
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    await new Promise((resolve) => {
+      setTimeout(resolve, 50);
+    });
     closeOpenClawAgentDatabasesForTest();
     fs.rmSync(tempDir, { recursive: true, force: true });
   });
diff --git a/src/config/sessions/session-history-eviction.ts b/src/config/sessions/session-history-eviction.ts
@@ -14,6 +14,7 @@ import {
   measureSessionPhysicalDiskUsage,
   pruneSessionTranscriptArchivesToHighWater,
   type SessionDiskBudgetSweepResult,
+  type SessionPhysicalDiskUsage,
 } from "./disk-budget.js";
 import { materializeSqliteSessionStateDeletePlans } from "./session-accessor.sqlite-archive.js";
 import { emitArchivedSqliteTranscriptUpdates } from "./session-accessor.sqlite-events.js";
@@ -305,7 +306,7 @@ async function enforceSessionHistoryMaintenanceSerialized(
   });
   const database = openOpenClawAgentDatabase(toDatabaseOptions(resolved));
   const archiveDirectory = resolveSqliteTranscriptArchiveDirectory(resolved);
-  let usage = await runExclusiveSqliteSessionWrite(resolved, async () => {
+  let usage: SessionPhysicalDiskUsage = await runExclusiveSqliteSessionWrite(resolved, async () => {
     reclaimSqliteFreePages(database);
     return await measureSessionPhysicalDiskUsage(params.storePath);
   });
diff --git a/src/gateway/server.sessions.reset-hooks.test.ts b/src/gateway/server.sessions.reset-hooks.test.ts
@@ -554,13 +554,10 @@ test("sessions.reset emits enriched session_end and session_start hooks", async
   expect(endEvent.sessionId).toBe("sess-main");
   expect(endEvent.sessionKey).toBe("agent:main:main");
   expect(endEvent.reason).toBe("new");
-  expect(endEvent.transcriptArchived).toBe(true);
-  const archivedSessionFile = expectStringWithPrefix(
-    path.basename(expectStringValue(endEvent.sessionFile, "archived session file")),
-    "sess-main.jsonl.reset.",
-    "archived session file",
-  );
-  expect(archivedSessionFile).toContain(".jsonl.reset.");
+  // Retained history: reset keeps the SQLite transcript searchable under the
+  // same key, so nothing is archived and no reset artifact file exists.
+  expect(endEvent.transcriptArchived).toBeUndefined();
+  expect(endEvent.sessionFile).toBeUndefined();
   expect(endEvent.nextSessionId).toBe(startEvent.sessionId);
   expectMainHookContext(endContext, "sess-main");
   expect(startEvent.sessionKey).toBe("agent:main:main");
diff --git a/src/gateway/server.sessions.store-rpc.test.ts b/src/gateway/server.sessions.store-rpc.test.ts
@@ -592,13 +592,15 @@ test("lists and patches session store via sessions.* RPC", async () => {
   const entryAfterReset = loadSessionEntry({ sessionKey: "agent:main:main", storePath });
   expect(entryAfterReset?.lastAccountId).toBe("work");
   expect(entryAfterReset?.lastThreadId).toBe("1737500000.123456");
+  // Retained history: reset rotates the live session id but keeps the old
+  // generation's transcript rows in SQLite.
   await expect(
     loadTranscriptRows({
       sessionId: "sess-main",
       sessionKey: "agent:main:main",
       storePath,
     }),
-  ).resolves.toEqual([]);
+  ).resolves.toHaveLength(3);
 
   const badThinking = await directSessionReq("sessions.patch", {
     key: "agent:main:main",
diff --git a/test/helpers/sqlite-sessions-transcripts-flip-proof.ts b/test/helpers/sqlite-sessions-transcripts-flip-proof.ts
@@ -2492,12 +2492,14 @@ function validateCheckpointInvariants(
     });
   }
   if (checkpoint.label === "after-sessions-reset") {
-    requireArchiveText(checkpoint, failures, {
-      description: "reset transcript archive",
-      includes: ["legacy hello", "sqlite user-facing send before reset"],
-      reason: "reset",
-      sessionId: context.legacySessionId,
-    });
+    // Retained history: reset rotates the live session id but keeps the old
+    // generation's SQLite rows searchable; no reset archive is produced.
+    if (findArchiveArtifact(checkpoint, { reason: "reset", sessionId: context.legacySessionId })) {
+      failures.push(`${checkpoint.label}: unexpected reset transcript archive`);
+    }
+    if (checkpoint.sqlite.transcriptEvents === 0) {
+      failures.push(`${checkpoint.label}: retained transcript rows missing after reset`);
+    }
   }
   if (checkpoint.label === "after-sessions-delete") {
     requireArchiveText(checkpoint, failures, {
diff --git a/test/scripts/sqlite-sessions-transcripts-flip-proof.built-cli.e2e.test.ts b/test/scripts/sqlite-sessions-transcripts-flip-proof.built-cli.e2e.test.ts
@@ -119,12 +119,14 @@ describe("SQLite sessions/transcripts flip built CLI proof", () => {
     const resetCheckpoint = report.checkpoints.find(
       (checkpoint) => checkpoint.label === "after-sessions-reset",
     );
+    // Retained history: reset keeps the old generation's SQLite rows and
+    // writes no reset archive artifact.
     const resetArchive = resetCheckpoint?.archiveArtifacts.find(
       (artifact) =>
         artifact.archiveReason === "reset" && artifact.archiveSessionId === report.legacySessionId,
     );
-    expect(resetArchive?.messageTexts).toContain("legacy hello");
-    expect(resetArchive?.messageTexts).toContain("sqlite user-facing send before reset");
+    expect(resetArchive).toBeUndefined();
+    expect(resetCheckpoint?.sqlite.transcriptEvents ?? 0).toBeGreaterThan(0);
     const sharedFirstCheckpoint = report.checkpoints.find(
       (checkpoint) => checkpoint.label === "after-shared-first-delete",
     );
diff --git a/test/scripts/sqlite-sessions-transcripts-flip-proof.e2e.test.ts b/test/scripts/sqlite-sessions-transcripts-flip-proof.e2e.test.ts
@@ -118,12 +118,14 @@ describe("SQLite sessions/transcripts flip proof harness", () => {
     const resetCheckpoint = report.checkpoints.find(
       (checkpoint) => checkpoint.label === "after-sessions-reset",
     );
+    // Retained history: reset keeps the old generation's SQLite rows and
+    // writes no reset archive artifact.
     const resetArchive = resetCheckpoint?.archiveArtifacts.find(
       (artifact) =>
         artifact.archiveReason === "reset" && artifact.archiveSessionId === report.legacySessionId,
     );
-    expect(resetArchive?.messageTexts).toContain("legacy hello");
-    expect(resetArchive?.messageTexts).toContain("sqlite user-facing send before reset");
+    expect(resetArchive).toBeUndefined();
+    expect(resetCheckpoint?.sqlite.transcriptEvents ?? 0).toBeGreaterThan(0);
     expect(
       report.checkpoints.some(
         (checkpoint) =>
