fix(sessions): retire stale direct dm rows after dmscope changes

BunsDev · BunsDev · commit 9583e2890a3c · 2026-05-05T19:02:36.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -102,6 +102,7 @@ Docs: https://docs.openclaw.ai
 - Gateway/HTTP: avoid loading managed outgoing-image media handlers for unrelated requests, so disabled OpenAI-compatible routes return 404 without waiting on lazy media sidecars. Thanks @vincentkoc.
 - Gateway/OpenAI-compatible: send the assistant role SSE chunk as soon as streaming chat-completion headers are accepted, so cold agent setup cannot leave `/v1/chat/completions` clients with a bodyless 200 response until their idle timeout fires.
 - Agents/media: avoid direct generated-media completion fallback while the announce-agent run is still pending, so async video and music completions do not duplicate raw media messages. (#77754)
+- Sessions cleanup: add `openclaw sessions cleanup --fix-dm-scope` so operators who return `session.dmScope` to `main` can dry-run and retire stale direct-DM session rows while preserving transcripts as deleted archives. Fixes #47561 and #45554. Thanks @BunsDev.
 - TUI/sessions: bound the session picker to recent rows and use exact lookup-style refreshes for the active session, so dusty stores no longer make TUI hydrate weeks-old transcripts before becoming responsive. Thanks @vincentkoc.
 - Doctor/gateway: report recent supervisor restart handoffs in `openclaw doctor --deep`, using the installed service environment when available so service-managed clean exits are visible in guided diagnostics. Thanks @shakkernerd.
 - Gateway/status: show recent supervisor restart handoffs in `openclaw gateway status --deep`, including JSON details, so clean service-managed restarts are reported as restart handoffs instead of opaque stopped-service diagnostics. Thanks @shakkernerd.
diff --git a/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift b/apps/macos/Sources/OpenClawProtocol/GatewayModels.swift
@@ -1568,19 +1568,22 @@ public struct SessionsCleanupParams: Codable, Sendable {
     public let enforce: Bool?
     public let activekey: String?
     public let fixmissing: Bool?
+    public let fixdmscope: Bool?
 
     public init(
         agent: String?,
         allagents: Bool?,
         enforce: Bool?,
         activekey: String?,
-        fixmissing: Bool?)
+        fixmissing: Bool?,
+        fixdmscope: Bool?)
     {
         self.agent = agent
         self.allagents = allagents
         self.enforce = enforce
         self.activekey = activekey
         self.fixmissing = fixmissing
+        self.fixdmscope = fixdmscope
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -1589,6 +1592,7 @@ public struct SessionsCleanupParams: Codable, Sendable {
         case enforce
         case activekey = "activeKey"
         case fixmissing = "fixMissing"
+        case fixdmscope = "fixDmScope"
     }
 }
 
diff --git a/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift b/apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift
@@ -1568,19 +1568,22 @@ public struct SessionsCleanupParams: Codable, Sendable {
     public let enforce: Bool?
     public let activekey: String?
     public let fixmissing: Bool?
+    public let fixdmscope: Bool?
 
     public init(
         agent: String?,
         allagents: Bool?,
         enforce: Bool?,
         activekey: String?,
-        fixmissing: Bool?)
+        fixmissing: Bool?,
+        fixdmscope: Bool?)
     {
         self.agent = agent
         self.allagents = allagents
         self.enforce = enforce
         self.activekey = activekey
         self.fixmissing = fixmissing
+        self.fixdmscope = fixdmscope
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -1589,6 +1592,7 @@ public struct SessionsCleanupParams: Codable, Sendable {
         case enforce
         case activekey = "activeKey"
         case fixmissing = "fixMissing"
+        case fixdmscope = "fixDmScope"
     }
 }
 
diff --git a/docs/cli/sessions.md b/docs/cli/sessions.md
@@ -93,6 +93,7 @@ openclaw sessions cleanup --agent work --dry-run
 openclaw sessions cleanup --all-agents --dry-run
 openclaw sessions cleanup --enforce
 openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
+openclaw sessions cleanup --dry-run --fix-dm-scope
 openclaw sessions cleanup --json
 ```
 
@@ -105,6 +106,7 @@ openclaw sessions cleanup --json
   - In text mode, dry-run prints a per-session action table (`Action`, `Key`, `Age`, `Model`, `Flags`) so you can see what would be kept vs removed.
 - `--enforce`: apply maintenance even when `session.maintenance.mode` is `warn`.
 - `--fix-missing`: remove entries whose transcript files are missing, even if they would not normally age/count out yet.
+- `--fix-dm-scope`: when `session.dmScope` is `main`, retire stale peer-keyed direct-DM rows left behind by earlier `per-peer`, `per-channel-peer`, or `per-account-channel-peer` routing. Use `--dry-run` first; applying the cleanup removes those rows from `sessions.json` and preserves their transcripts as deleted archives.
 - `--active-key <key>`: protect a specific active key from disk-budget eviction. Durable external conversation pointers, such as group sessions and thread-scoped chat sessions, are also kept by age/count/disk-budget maintenance.
 - `--agent <id>`: run cleanup for one configured agent store.
 - `--all-agents`: run cleanup for all configured agent stores.
@@ -128,6 +130,8 @@ traffic. Use `--store <path>` for explicit offline repair of a store file.
       "storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
       "beforeCount": 120,
       "afterCount": 80,
+      "missing": 0,
+      "dmScopeRetired": 0,
       "pruned": 40,
       "capped": 0
     },
@@ -136,6 +140,8 @@ traffic. Use `--store <path>` for explicit offline repair of a store file.
       "storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
       "beforeCount": 18,
       "afterCount": 18,
+      "missing": 0,
+      "dmScopeRetired": 0,
       "pruned": 0,
       "capped": 0
     }
diff --git a/docs/concepts/session.md b/docs/concepts/session.md
@@ -131,6 +131,12 @@ Maintenance preserves durable external conversation pointers, including group
 sessions and thread-scoped chat sessions, while still allowing synthetic cron,
 hook, heartbeat, ACP, and sub-agent entries to age out.
 
+If you previously used direct-message isolation and later returned
+`session.dmScope` to `main`, preview stale peer-keyed DM rows with
+`openclaw sessions cleanup --dry-run --fix-dm-scope`. Applying the same flag
+retires those old direct-DM rows and keeps their transcripts as deleted
+archives.
+
 Preview with `openclaw sessions cleanup --dry-run`.
 
 ## Inspecting sessions
diff --git a/src/cli/program/register.status-health-sessions.test.ts b/src/cli/program/register.status-health-sessions.test.ts
@@ -239,6 +239,7 @@ describe("registerStatusHealthSessionsCommands", () => {
       "--dry-run",
       "--enforce",
       "--fix-missing",
+      "--fix-dm-scope",
       "--active-key",
       "agent:main:main",
       "--json",
@@ -252,6 +253,7 @@ describe("registerStatusHealthSessionsCommands", () => {
         dryRun: true,
         enforce: true,
         fixMissing: true,
+        fixDmScope: true,
         activeKey: "agent:main:main",
         json: true,
       }),
diff --git a/src/cli/program/register.status-health-sessions.ts b/src/cli/program/register.status-health-sessions.ts
@@ -182,6 +182,11 @@ export function registerStatusHealthSessionsCommands(program: Command) {
       "Remove store entries whose transcript files are missing (bypasses age/count retention)",
       false,
     )
+    .option(
+      "--fix-dm-scope",
+      "Retire stale direct-DM session rows that no longer match session.dmScope=main",
+      false,
+    )
     .option("--active-key <key>", "Protect this session key from budget-eviction")
     .option("--json", "Output JSON", false)
     .addHelpText(
@@ -193,6 +198,10 @@ export function registerStatusHealthSessionsCommands(program: Command) {
             "openclaw sessions cleanup --dry-run --fix-missing",
             "Also preview pruning entries with missing transcript files.",
           ],
+          [
+            "openclaw sessions cleanup --dry-run --fix-dm-scope",
+            "Preview stale direct-DM rows after returning dmScope to main.",
+          ],
           ["openclaw sessions cleanup --enforce", "Apply maintenance now."],
           ["openclaw sessions cleanup --agent work --dry-run", "Preview one agent store."],
           ["openclaw sessions cleanup --all-agents --dry-run", "Preview all agent stores."],
@@ -220,6 +229,7 @@ export function registerStatusHealthSessionsCommands(program: Command) {
             dryRun: Boolean(opts.dryRun),
             enforce: Boolean(opts.enforce),
             fixMissing: Boolean(opts.fixMissing),
+            fixDmScope: Boolean(opts.fixDmScope),
             activeKey: opts.activeKey as string | undefined,
             json: Boolean(opts.json || parentOpts?.json),
           },
diff --git a/src/commands/sessions-cleanup.test.ts b/src/commands/sessions-cleanup.test.ts
@@ -119,7 +119,11 @@ describe("sessionsCleanupCommand", () => {
         staleKeys: Set<string>;
         cappedKeys: Set<string>;
         budgetEvictedKeys: Set<string>;
+        dmScopeRetiredKeys: Set<string>;
       }) => {
+        if (params.dmScopeRetiredKeys.has(params.key)) {
+          return "retire-dm-scope";
+        }
         if (params.missingKeys.has(params.key)) {
           return "prune-missing";
         }
@@ -181,6 +185,7 @@ describe("sessionsCleanupCommand", () => {
           beforeCount: 3,
           afterCount: 1,
           missing: 0,
+          dmScopeRetired: 0,
           pruned: 0,
           capped: 2,
           diskBudget: {
@@ -245,6 +250,7 @@ describe("sessionsCleanupCommand", () => {
       beforeCount: 3,
       afterCount: 1,
       missing: 0,
+      dmScopeRetired: 0,
       pruned: 2,
       capped: 0,
       diskBudget: null,
@@ -286,6 +292,7 @@ describe("sessionsCleanupCommand", () => {
             beforeCount: 2,
             afterCount: 1,
             missing: 0,
+            dmScopeRetired: 0,
             pruned: 1,
             capped: 0,
             diskBudget: {
@@ -305,6 +312,7 @@ describe("sessionsCleanupCommand", () => {
           staleKeys: new Set<string>(),
           cappedKeys: new Set<string>(),
           budgetEvictedKeys: new Set<string>(),
+          dmScopeRetiredKeys: new Set<string>(),
         },
       ],
       appliedSummaries: [],
@@ -347,6 +355,7 @@ describe("sessionsCleanupCommand", () => {
             beforeCount: 1,
             afterCount: 0,
             missing: 1,
+            dmScopeRetired: 0,
             pruned: 0,
             capped: 0,
             diskBudget: null,
@@ -357,6 +366,7 @@ describe("sessionsCleanupCommand", () => {
           staleKeys: new Set<string>(),
           cappedKeys: new Set<string>(),
           budgetEvictedKeys: new Set<string>(),
+          dmScopeRetiredKeys: new Set<string>(),
         },
       ],
       appliedSummaries: [],
@@ -393,6 +403,7 @@ describe("sessionsCleanupCommand", () => {
             beforeCount: 2,
             afterCount: 1,
             missing: 0,
+            dmScopeRetired: 0,
             pruned: 1,
             capped: 0,
             unreferencedArtifacts: {
@@ -412,6 +423,7 @@ describe("sessionsCleanupCommand", () => {
           staleKeys: new Set(["stale"]),
           cappedKeys: new Set<string>(),
           budgetEvictedKeys: new Set<string>(),
+          dmScopeRetiredKeys: new Set<string>(),
         },
       ],
       appliedSummaries: [],
@@ -450,6 +462,7 @@ describe("sessionsCleanupCommand", () => {
             beforeCount: 1,
             afterCount: 0,
             missing: 0,
+            dmScopeRetired: 0,
             pruned: 1,
             capped: 0,
             diskBudget: null,
@@ -460,6 +473,7 @@ describe("sessionsCleanupCommand", () => {
           staleKeys: new Set(["stale"]),
           cappedKeys: new Set<string>(),
           budgetEvictedKeys: new Set<string>(),
+          dmScopeRetiredKeys: new Set<string>(),
         },
         {
           summary: {
@@ -470,6 +484,7 @@ describe("sessionsCleanupCommand", () => {
             beforeCount: 1,
             afterCount: 0,
             missing: 0,
+            dmScopeRetired: 0,
             pruned: 1,
             capped: 0,
             diskBudget: null,
@@ -480,6 +495,7 @@ describe("sessionsCleanupCommand", () => {
           staleKeys: new Set(["stale"]),
           cappedKeys: new Set<string>(),
           budgetEvictedKeys: new Set<string>(),
+          dmScopeRetiredKeys: new Set<string>(),
         },
       ],
       appliedSummaries: [],
diff --git a/src/commands/sessions-cleanup.ts b/src/commands/sessions-cleanup.ts
@@ -25,7 +25,7 @@ import {
   toSessionDisplayRows,
 } from "./sessions-table.js";
 
-const ACTION_PAD = 12;
+const ACTION_PAD = 16;
 
 type SessionCleanupActionRow = ReturnType<typeof toSessionDisplayRows>[number] & {
   action: ReturnType<typeof resolveSessionCleanupAction>;
@@ -48,6 +48,9 @@ function formatCleanupActionCell(
   if (action === "prune-stale") {
     return theme.warn(label);
   }
+  if (action === "retire-dm-scope") {
+    return theme.warn(label);
+  }
   if (action === "cap-overflow") {
     return theme.accentBright(label);
   }
@@ -60,6 +63,7 @@ function buildActionRows(params: {
   staleKeys: Set<string>;
   cappedKeys: Set<string>;
   budgetEvictedKeys: Set<string>;
+  dmScopeRetiredKeys: Set<string>;
 }): SessionCleanupActionRow[] {
   return toSessionDisplayRows(params.beforeStore).map((row) =>
     Object.assign({}, row, {
@@ -69,6 +73,7 @@ function buildActionRows(params: {
         staleKeys: params.staleKeys,
         cappedKeys: params.cappedKeys,
         budgetEvictedKeys: params.budgetEvictedKeys,
+        dmScopeRetiredKeys: params.dmScopeRetiredKeys,
       }),
     }),
   );
@@ -91,6 +96,7 @@ function renderStoreDryRunPlan(params: {
     `Entries: ${params.summary.beforeCount} -> ${params.summary.afterCount} (remove ${params.summary.beforeCount - params.summary.afterCount})`,
   );
   params.runtime.log(`Would prune missing transcripts: ${params.summary.missing}`);
+  params.runtime.log(`Would retire stale direct DM sessions: ${params.summary.dmScopeRetired}`);
   params.runtime.log(`Would prune stale: ${params.summary.pruned}`);
   params.runtime.log(`Would cap overflow: ${params.summary.capped}`);
   if (params.summary.unreferencedArtifacts?.scannedFiles) {
@@ -169,6 +175,7 @@ async function maybeRunGatewayCleanup(
         enforce: opts.enforce,
         activeKey: opts.activeKey,
         fixMissing: opts.fixMissing,
+        fixDmScope: opts.fixDmScope,
       },
       mode: GATEWAY_CLIENT_MODES.CLI,
       clientName: GATEWAY_CLIENT_NAMES.CLI,
diff --git a/src/config/sessions/cleanup-service.ts b/src/config/sessions/cleanup-service.ts
diff --git a/src/config/sessions/store.pruning.integration.test.ts b/src/config/sessions/store.pruning.integration.test.ts
diff --git a/src/gateway/protocol/schema/sessions.ts b/src/gateway/protocol/schema/sessions.ts
diff --git a/src/gateway/server-methods/sessions.ts b/src/gateway/server-methods/sessions.ts
