fix(matrix): warn on accumulated token storage roots (#97353)

outdog-hwh · web-flow · commit f4201578e50c · 2026-06-28T12:34:52.000-07:00
diff --git a/docs/channels/matrix.md b/docs/channels/matrix.md
@@ -499,6 +499,8 @@ openclaw matrix devices prune-stale
 
     Encrypted runtime state lives under `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/` and includes the sync store, crypto store, recovery key, IDB snapshot, thread bindings, and startup verification state. When the token changes but the account identity stays the same, OpenClaw reuses the best existing root so prior state remains visible.
 
+    A single older token-hash root can be a normal token-rotation continuity path. If OpenClaw logs `matrix: multiple populated token-hash storage roots detected`, inspect the account directory and archive stale sibling roots only after confirming the selected active root is healthy. Prefer moving stale roots into an `_archive/` directory over deleting them immediately.
+
   </Accordion>
 </AccordionGroup>
 
diff --git a/extensions/matrix/src/matrix/client/storage.test.ts b/extensions/matrix/src/matrix/client/storage.test.ts
@@ -85,12 +85,21 @@ describe("matrix client storage paths", () => {
     }
   });
 
+  function createTestLogger() {
+    return {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+  }
+
   function setupStateDir(
     cfg: Record<string, unknown> = {
       channels: {
         matrix: {},
       },
     },
+    logger = createTestLogger(),
   ): string {
     const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-matrix-storage-"));
     const stateDir = path.join(homeDir, ".openclaw");
@@ -99,11 +108,7 @@ describe("matrix client storage paths", () => {
     installMatrixTestRuntime({
       cfg,
       logging: {
-        getChildLogger: () => ({
-          info: () => {},
-          warn: () => {},
-          error: () => {},
-        }),
+        getChildLogger: () => logger,
       },
       stateDir,
     });
@@ -662,7 +667,8 @@ describe("matrix client storage paths", () => {
   });
 
   it("reuses an existing token-hash storage root for the same device after the access token changes", () => {
-    setupStateDir();
+    const logger = createTestLogger();
+    setupStateDir(undefined, logger);
     const oldStoragePaths = seedExistingStorageRoot({
       accessToken: "secret-token-old",
       deviceId: "DEVICE123",
@@ -683,6 +689,54 @@ describe("matrix client storage paths", () => {
     expect(rotatedStoragePaths.rootDir).toBe(oldStoragePaths.rootDir);
     expect(rotatedStoragePaths.tokenHash).toBe(oldStoragePaths.tokenHash);
     expect(rotatedStoragePaths.storagePath).toBe(oldStoragePaths.storagePath);
+    expect(logger.warn).not.toHaveBeenCalled();
+  });
+
+  it("warns with structured metadata when populated token-hash storage roots accumulate", () => {
+    const logger = createTestLogger();
+    const stateDir = setupStateDir(undefined, logger);
+    const oldStoragePaths = seedExistingStorageRoot({
+      accessToken: "secret-token-old",
+      deviceId: "DEVICE123",
+      storageMeta: {
+        homeserver: defaultStorageAuth.homeserver,
+        userId: defaultStorageAuth.userId,
+        accountId: "default",
+        accessTokenHash: resolveDefaultStoragePaths({ accessToken: "secret-token-old" }).tokenHash,
+        deviceId: "DEVICE123",
+      },
+    });
+    const canonicalPaths = seedCanonicalStorageRoot({
+      stateDir,
+      accessToken: "secret-token-new",
+      storageMeta: {
+        homeserver: defaultStorageAuth.homeserver,
+        userId: defaultStorageAuth.userId,
+        accountId: "default",
+        accessTokenHash: resolveDefaultStoragePaths({ accessToken: "secret-token-new" }).tokenHash,
+        deviceId: "DEVICE123",
+      },
+    });
+    fs.mkdirSync(path.join(canonicalPaths.rootDir, "crypto"), { recursive: true });
+
+    const resolvedPaths = resolveDefaultStoragePaths({
+      accessToken: "secret-token-new",
+      deviceId: "DEVICE123",
+    });
+
+    expect(resolvedPaths.rootDir).toBe(canonicalPaths.rootDir);
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledWith(
+      "matrix: multiple populated token-hash storage roots detected",
+      {
+        parentDir: path.dirname(canonicalPaths.rootDir),
+        canonicalTokenHash: canonicalPaths.tokenHash,
+        selectedTokenHash: canonicalPaths.tokenHash,
+        populatedTokenHashes: [canonicalPaths.tokenHash, oldStoragePaths.tokenHash],
+        populatedSiblingTokenHashes: [oldStoragePaths.tokenHash],
+        populatedRootCount: 2,
+      },
+    );
   });
 
   it("reads legacy storage metadata until doctor migrates it to SQLite", () => {
diff --git a/extensions/matrix/src/matrix/client/storage.ts b/extensions/matrix/src/matrix/client/storage.ts
@@ -139,6 +139,13 @@ function resolveStorageRootMtimeMs(rootDir: string): number {
   }
 }
 
+type PopulatedMatrixStorageRoot = {
+  tokenHash: string;
+  rootDir: string;
+  score: number;
+  mtimeMs: number;
+};
+
 export function normalizeMatrixStorageMetadata(value: unknown): MatrixStorageMetadata | null {
   if (!isRecord(value)) {
     return null;
@@ -251,11 +258,12 @@ function resolvePreferredMatrixStorageRoot(params: {
 } {
   const parentDir = path.dirname(params.canonicalRootDir);
   const bestCurrentScore = scoreStorageRoot(params.canonicalRootDir);
+  const bestCurrentMtimeMs = resolveStorageRootMtimeMs(params.canonicalRootDir);
   let best = {
     rootDir: params.canonicalRootDir,
     tokenHash: params.canonicalTokenHash,
     score: bestCurrentScore,
-    mtimeMs: resolveStorageRootMtimeMs(params.canonicalRootDir),
+    mtimeMs: bestCurrentMtimeMs,
   };
 
   // Without a confirmed device identity, reusing a populated sibling root after
@@ -267,18 +275,6 @@ function resolvePreferredMatrixStorageRoot(params: {
     };
   }
 
-  const canonicalMetadata = readStoredRootMetadata(params.canonicalRootDir);
-  if (
-    canonicalMetadata.accessTokenHash === params.canonicalTokenHash &&
-    canonicalMetadata.deviceId?.trim() === params.deviceId.trim() &&
-    canonicalMetadata.currentTokenStateClaimed === true
-  ) {
-    return {
-      rootDir: best.rootDir,
-      tokenHash: best.tokenHash,
-    };
-  }
-
   let siblingEntries: fs.Dirent[];
   try {
     siblingEntries = fs.readdirSync(parentDir, { withFileTypes: true });
@@ -289,7 +285,9 @@ function resolvePreferredMatrixStorageRoot(params: {
     };
   }
 
-  for (const entry of siblingEntries) {
+  const compatiblePopulatedSiblings: PopulatedMatrixStorageRoot[] = [];
+  const populatedTokenHashes = bestCurrentScore > 0 ? [params.canonicalTokenHash] : [];
+  for (const entry of siblingEntries.toSorted((a, b) => a.name.localeCompare(b.name))) {
     if (!entry.isDirectory()) {
       continue;
     }
@@ -315,22 +313,52 @@ function resolvePreferredMatrixStorageRoot(params: {
     if (candidateScore <= 0) {
       continue;
     }
-    const candidateMtimeMs = resolveStorageRootMtimeMs(candidateRootDir);
-    if (
-      candidateScore > best.score ||
-      (best.rootDir !== params.canonicalRootDir &&
-        candidateScore === best.score &&
-        candidateMtimeMs > best.mtimeMs)
-    ) {
-      best = {
-        rootDir: candidateRootDir,
-        tokenHash: entry.name,
-        score: candidateScore,
-        mtimeMs: candidateMtimeMs,
-      };
+    populatedTokenHashes.push(entry.name);
+    compatiblePopulatedSiblings.push({
+      rootDir: candidateRootDir,
+      tokenHash: entry.name,
+      score: candidateScore,
+      mtimeMs: resolveStorageRootMtimeMs(candidateRootDir),
+    });
+  }
+
+  const canonicalMetadata = readStoredRootMetadata(params.canonicalRootDir);
+  const shouldKeepCanonicalCurrentRoot =
+    canonicalMetadata.accessTokenHash === params.canonicalTokenHash &&
+    canonicalMetadata.deviceId?.trim() === params.deviceId.trim() &&
+    canonicalMetadata.currentTokenStateClaimed === true;
+
+  if (!shouldKeepCanonicalCurrentRoot) {
+    for (const candidate of compatiblePopulatedSiblings) {
+      if (
+        candidate.score > best.score ||
+        (best.rootDir !== params.canonicalRootDir &&
+          candidate.score === best.score &&
+          candidate.mtimeMs > best.mtimeMs)
+      ) {
+        best = {
+          rootDir: candidate.rootDir,
+          tokenHash: candidate.tokenHash,
+          score: candidate.score,
+          mtimeMs: candidate.mtimeMs,
+        };
+      }
     }
   }
 
+  if (populatedTokenHashes.length > 1) {
+    getMatrixRuntime()
+      .logging.getChildLogger({ module: "matrix-storage" })
+      .warn("matrix: multiple populated token-hash storage roots detected", {
+        parentDir,
+        canonicalTokenHash: params.canonicalTokenHash,
+        selectedTokenHash: best.tokenHash,
+        populatedTokenHashes,
+        populatedSiblingTokenHashes: compatiblePopulatedSiblings.map((root) => root.tokenHash),
+        populatedRootCount: populatedTokenHashes.length,
+      });
+  }
+
   return {
     rootDir: best.rootDir,
     tokenHash: best.tokenHash,
