Matrix-js: show explicit backup issue in verify status

extensions/matrix-js/src/cli.test.ts

@@ -254,6 +254,33 @@ describe("matrix-js CLI verification commands", () => {
     expect(setMatrixSdkLogModeMock).toHaveBeenCalledWith("quiet");
   });
 
+  it("shows explicit backup issue in default status output", async () => {
+    getMatrixVerificationStatusMock.mockResolvedValue({
+      encryptionEnabled: true,
+      verified: true,
+      userId: "@bot:example.org",
+      deviceId: "DEVICE123",
+      backupVersion: "5256",
+      backup: {
+        serverVersion: "5256",
+        activeVersion: null,
+        trusted: true,
+        matchesDecryptionKey: false,
+        decryptionKeyCached: false,
+      },
+      recoveryKeyStored: true,
+      recoveryKeyCreatedAt: "2026-02-25T20:10:11.000Z",
+      pendingVerifications: 0,
+    });
+    const program = buildProgram();
+
+    await program.parseAsync(["matrix-js", "verify", "status"], { from: "user" });
+
+    expect(console.log).toHaveBeenCalledWith(
+      "Backup issue: backup key mismatch (this device does not have the matching backup decryption key)",
+    );
+  });
+
   it("prints backup health lines for verify backup status in verbose mode", async () => {
     getMatrixRoomKeyBackupStatusMock.mockResolvedValue({
       serverVersion: "2",

extensions/matrix-js/src/cli.ts

@@ -119,6 +119,32 @@ function printBackupSummary(backup: MatrixCliBackupStatus): void {
   }
 }
 
+function describeBackupIssue(backup: MatrixCliBackupStatus): string | null {
+  if (!backup.serverVersion) {
+    return "no room-key backup exists on the homeserver";
+  }
+  if (backup.matchesDecryptionKey === false) {
+    return "backup key mismatch (this device does not have the matching backup decryption key)";
+  }
+  if (backup.decryptionKeyCached === false) {
+    return "backup decryption key is not loaded on this device";
+  }
+  if (backup.trusted === false) {
+    return "backup signature chain is not trusted by this device";
+  }
+  if (!backup.activeVersion) {
+    return "backup exists but is not active on this device";
+  }
+  if (
+    backup.trusted === null ||
+    backup.matchesDecryptionKey === null ||
+    backup.decryptionKeyCached === null
+  ) {
+    return "backup trust state could not be fully determined";
+  }
+  return null;
+}
+
 function buildVerificationGuidance(status: MatrixCliVerificationStatus): string[] {
   const backup = resolveBackupStatus(status);
   const nextSteps = new Set<string>();
@@ -162,6 +188,10 @@ function printVerificationStatus(status: MatrixCliVerificationStatus, verbose =
   const backup = resolveBackupStatus(status);
   console.log(`Verified: ${status.verified ? "yes" : "no"}`);
   printBackupSummary(backup);
+  const backupIssue = describeBackupIssue(backup);
+  if (backupIssue) {
+    console.log(`Backup issue: ${backupIssue}`);
+  }
   if (verbose) {
     console.log("Diagnostics:");
     console.log(`User: ${status.userId ?? "unknown"}`);